@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/framework/express/semgrep/express.yml

@@ -0,0 +1,71 @@
+rules:
+    - id: gspot.express.raw-query-interpolation
+      patterns:
+          - pattern: $DB.$METHOD(`...${req.$SOURCE.$FIELD}...`, ...)
+          - metavariable-regex:
+                metavariable: $METHOD
+                regex: ^(query|execute|raw|\$queryRawUnsafe)$
+          - metavariable-regex:
+                metavariable: $SOURCE
+                regex: ^(body|query|params)$
+      message: 'SQL injection risk: request data is interpolated into a database call.
+          Use parameterised queries or an ORM.'
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-89
+          category: security
+    - id: gspot.express.unvalidated-redirect
+      patterns:
+          - pattern-either:
+                - pattern: res.redirect(req.body.$VALUE)
+                - pattern: res.redirect(req.query.$VALUE)
+                - pattern: res.redirect(req.params.$VALUE)
+      message: 'Open redirect: request data is passed directly to res.redirect().
+          Validate against an allowlist of URLs.'
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-601
+          category: security
+    - id: gspot.express.res-send-raw-input
+      patterns:
+          - pattern-either:
+                - pattern: res.send(req.$SOURCE.$FIELD)
+                - pattern: res.send(`...${req.$SOURCE.$FIELD}...`)
+          - metavariable-regex:
+                metavariable: $SOURCE
+                regex: ^(body|query|params)$
+      message: 'Reflected XSS risk: request data is sent as text or HTML. Escape HTML
+          output or use res.json() to send JSON.'
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-79
+          category: security
+    - id: gspot.express.no-stack-trace-in-response
+      patterns:
+          - pattern-either:
+                - pattern: 'res.send({..., stack: $ERR.stack, ...})'
+                - pattern: 'res.json({..., stack: $ERR.stack, ...})'
+                - pattern: 'res.status(...).send({..., stack: $ERR.stack, ...})'
+                - pattern: 'res.status(...).json({..., stack: $ERR.stack, ...})'
+      message: Stack traces in API responses leak internal implementation details. Log
+          the stack server-side and return a generic error message.
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-209
+          category: security

package/configurations/framework/fastapi/manifest.toml

@@ -0,0 +1,11 @@
+[configuration]
+title = "FastAPI"
+requires = ["python"]
+suggests = ["openapi"]
+description = "Checks FastAPI route declarations with Ruff. Adds Semgrep request-handling rules when security is selected and suggests the OpenAPI configuration."
+
+[detect]
+dependencies = ["fastapi"]
+
+[ruff_rules]
+recommended = ["FAST001", "FAST002", "FAST003"]

package/configurations/framework/fastapi/rules/FASTAPI.md

@@ -0,0 +1,100 @@
+# FastAPI
+
+Structure, parameters, schemas, responses, errors, and the runtime of a Python project on FastAPI
+and Pydantic v2.
+
+## Structure
+
+<!-- level: all -->
+
+Path operations adapt HTTP input to application calls and results to HTTP output; business logic
+lives outside them. One main module creates the `FastAPI` object and wires routers, global
+dependencies, middleware, exception handlers, and startup. Routers group related operations under
+a prefix that does not end in `/`, and imports use their domain, `items.router` and `users.router`.
+Database, SDK, and service clients stay out of import-time work, and nothing patches `sys.path`.
+
+```python
+"""Expose a fixed catalog with validated identifiers and public responses."""
+
+from typing import Annotated
+
+from fastapi import Path, FastAPI, APIRouter, HTTPException, status
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+    """Public catalog item."""
+
+    name: str
+
+
+CATALOG = (Item(name="Notebook"), Item(name="Pencil"))
+router = APIRouter(prefix="/items", tags=["items"])
+
+
+@router.get("/{item_id}")
+def get_item(item_id: Annotated[int, Path(ge=0)]) -> Item:
+    """Return one catalog item or a public not-found response."""
+    if item_id >= len(CATALOG):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Item not found")
+    return CATALOG[item_id]
+
+
+app = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+app.include_router(router)
+```
+
+## Parameters
+
+`Annotated[..., Query(...)]`, `Path`, `Body`, `Header`, `Cookie`, `Form`, `File`, or `Depends`;
+a plain scalar supplies a query parameter. A parameter without a default requires a value, even when it
+accepts `None`. Constraints such as `max_length` or `ge` belong at the boundary when the public interface requires them. Use a dependency for a check that needs a database or authorization state, not
+a validator. Declare fixed routes such as `/users/me` before `/users/{user_id}`, and group
+pagination or filter parameters into a query model with `extra="forbid"`.
+
+Forms need `python-multipart`, and one operation never mixes JSON body fields with form fields
+or files. Uploads arrive as `UploadFile`, bounded in count and size; `bytes` holds only small
+values. Never use a filename as a filesystem path, a content type never proves safety, and never log uploaded
+contents.
+
+## Schemas and responses
+
+Pydantic models define the schemas where data enters or leaves. Use separate classes for create, read, and update shapes when
+their fields differ. Never return an input with passwords or tokens as the response. Known JSON
+shapes use nested models with typed containers. Use `UUID` for identifiers, timezone-aware instants across a
+boundary, and `Decimal` for money. A partial update reads
+`model_dump(exclude_unset=True)`, merges with the stored value, and validates the complete model,
+because `model_copy(update=...)` validates nothing.
+
+The return type defines the public schema; `response_model` serves a returned object of another
+shape. A dedicated output model filters fields, never `response_model_exclude`, which still
+documents the full model. A response validation failure shows a server bug. Fix the data or
+the schema.
+
+## Status codes and errors
+
+Non-default success codes go in the decorator with `fastapi.status` constants: 201 for creation,
+202 for accepted work, and 204 for a deliberate empty body. Raise `HTTPException` rather than returning it. Its `detail` supplies a public error message. Existence and
+authorization checks answer alike, so responses do not reveal a private resource. Global exception
+handlers return the standard error shape and never echo a validation error's body.
+
+## Runtime
+
+- Declare a path operation or dependency `async def` when it awaits async libraries and `def` when it
+  calls blocking code; a blocking call inside `async def` stalls the event loop. Run CPU-heavy work in a worker process, not in `async def`.
+- Dependencies carry request-scoped concerns: authentication, sessions, pagination, and
+  reusable validation. A `yield` dependency owns one resource, cleans up in `finally`, and
+  re-raises what it catches.
+- Authentication that appears in OpenAPI uses the security utilities. A JSON Web Token (JWT) verifier allows an
+  explicit algorithm list and requires `exp` and `sub`.
+- `BackgroundTasks` runs small follow-up work after the response; durable or heavy work goes to
+  a queue. Middleware holds cross-cutting HTTP behavior only, and the last middleware added runs
+  outermost.
+- Turn OpenAPI and the interactive docs off unless a typed setting turns them on, and the schema
+  exposes no internal or admin routes.
+
+## Testing
+
+Tests cover the HTTP contract through the test client: status codes, bodies, headers, and
+authentication. Replace external systems with dependency overrides at the application
+boundary. Tests cover the application rather than FastAPI's routing implementation.

package/configurations/framework/fastapi/semgrep/fastapi.yml

@@ -0,0 +1,44 @@
+rules:
+    - id: gspot.fastapi.cors-wildcard-with-credentials
+      patterns:
+          - pattern: $APP.add_middleware(CORSMiddleware, ..., allow_origins=["*"], ...,
+                allow_credentials=True, ...)
+      message: Every origin is allowed together with credentials, so any site reads an
+          authenticated response. List the origins.
+      languages:
+          - python
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-942
+          category: security
+    - id: gspot.fastapi.debug-enabled
+      pattern: FastAPI(..., debug=True, ...)
+      message: Debug mode returns tracebacks to the client. Read the flag from
+          configuration, off by default.
+      languages:
+          - python
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-489
+          category: security
+    - id: gspot.fastapi.exception-text-in-response
+      patterns:
+          - pattern-either:
+                - pattern: HTTPException(..., detail=str($ERROR), ...)
+                - pattern: HTTPException(..., detail=f"...{$ERROR}...", ...)
+          - pattern-inside: |-
+                try:
+                    ...
+                except $TYPE as $ERROR:
+                    ...
+      message: The text of an internal exception goes to the client. Log it, and
+          return a stable message.
+      languages:
+          - python
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-209
+          category: security

package/configurations/framework/nestjs/eslint-presets.json

@@ -0,0 +1,62 @@
+{
+    "recommended": {
+        "package": "@darraghor/eslint-plugin-nestjs-typed",
+        "version": "7.5.5",
+        "source": "configs.flatRecommended",
+        "blocks": [
+            { "parser": true },
+            {
+                "parser": false,
+                "rules": {
+                    "@darraghor/nestjs-typed/provided-injected-should-match-factory-parameters": "error",
+                    "@darraghor/nestjs-typed/injectable-should-be-provided": [
+                        "error",
+                        { "src": ["src/**/*.ts"], "filterFromPaths": ["node_modules", ".test.", ".spec."] }
+                    ],
+                    "@darraghor/nestjs-typed/api-property-matches-property-optionality": "error",
+                    "@darraghor/nestjs-typed/api-method-should-specify-api-response": "error",
+                    "@darraghor/nestjs-typed/controllers-should-supply-api-tags": "error",
+                    "@darraghor/nestjs-typed/api-enum-property-best-practices": "error",
+                    "@darraghor/nestjs-typed/api-property-returning-array-should-set-array": "error",
+                    "@darraghor/nestjs-typed/validation-pipe-should-use-forbid-unknown": "error",
+                    "@darraghor/nestjs-typed/param-decorator-name-matches-route-param": "error",
+                    "@darraghor/nestjs-typed/validated-non-primitive-property-needs-type-decorator": "error",
+                    "@darraghor/nestjs-typed/validate-nested-of-array-should-set-each": "error",
+                    "@darraghor/nestjs-typed/all-properties-are-whitelisted": "error",
+                    "@darraghor/nestjs-typed/all-properties-have-explicit-defined": "error",
+                    "@darraghor/nestjs-typed/api-methods-should-be-guarded": "off",
+                    "@darraghor/nestjs-typed/api-method-should-specify-api-operation": "off",
+                    "@darraghor/nestjs-typed/sort-module-metadata-arrays": "off",
+                    "@darraghor/nestjs-typed/no-duplicate-decorators": "error",
+                    "@darraghor/nestjs-typed/use-injectable-provided-token": "error",
+                    "@darraghor/nestjs-typed/api-property-should-have-api-extra-models": "error",
+                    "@darraghor/nestjs-typed/api-operation-summary-description-capitalized": "error",
+                    "@darraghor/nestjs-typed/use-dependency-injection": "off",
+                    "@darraghor/nestjs-typed/use-correct-endpoint-naming-convention": "off",
+                    "@darraghor/nestjs-typed/forward-ref-injection-should-use-wrapper-type": "error",
+                    "@darraghor/nestjs-typed/swagger-file-upload-should-be-documented": "error",
+                    "@darraghor/nestjs-typed/uploaded-file-should-be-validated": "error"
+                }
+            }
+        ]
+    },
+    "noSwagger": {
+        "package": "@darraghor/eslint-plugin-nestjs-typed",
+        "version": "7.5.5",
+        "source": "configs.flatNoSwagger",
+        "blocks": [
+            {
+                "parser": false,
+                "rules": {
+                    "@darraghor/nestjs-typed/api-property-matches-property-optionality": "off",
+                    "@darraghor/nestjs-typed/api-method-should-specify-api-response": "off",
+                    "@darraghor/nestjs-typed/api-method-should-specify-api-operation": "off",
+                    "@darraghor/nestjs-typed/controllers-should-supply-api-tags": "off",
+                    "@darraghor/nestjs-typed/api-enum-property-best-practices": "off",
+                    "@darraghor/nestjs-typed/api-property-returning-array-should-set-array": "off",
+                    "@darraghor/nestjs-typed/swagger-file-upload-should-be-documented": "off"
+                }
+            }
+        ]
+    }
+}

package/configurations/framework/nestjs/manifest.toml

@@ -0,0 +1,52 @@
+[prefix_collisions]
+kinds = ["controller", "service", "module", "guard", "pipe", "filter", "interceptor", "middleware", "decorator", "gateway", "resolver", "repository", "entity", "dto", "strategy", "provider"]
+
+[configuration]
+title = "NestJS"
+requires = ["typescript"]
+suggests = []
+description = "A NestJS service: the compiler options decorators need, the NestJS plugin rules for providers, routes, and DTOs, and no circular modules."
+
+[detect]
+dependencies = ["@nestjs/core"]
+filenames = ["nest-cli.json"]
+
+[files]
+filenames = ["nest-cli.json"]
+
+[[tool]]
+name = "@darraghor/eslint-plugin-nestjs-typed"
+rule_prefix = "@darraghor/nestjs-typed"
+kind = "library"
+version = "7.5.5"
+npm = "@darraghor/eslint-plugin-nestjs-typed"
+
+[eslint]
+all_level_rules = ["@darraghor/nestjs-typed/api-operation-summary-description-capitalized"]
+
+[eslint.presets.recommended]
+package = "@darraghor/eslint-plugin-nestjs-typed"
+source = "configs.flatRecommended"
+
+[eslint.presets.noSwagger]
+package = "@darraghor/eslint-plugin-nestjs-typed"
+source = "configs.flatNoSwagger"
+
+[[eslint.rules_off]]
+rules = ["gspot/no-trivial-files", "gspot/no-trivial-functions"]
+files = ["**/*.module.ts"]
+reason = "A Nest module is an empty decorated class that registers providers and controllers, which is the shape Nest asks for."
+
+[[eslint.selectors]]
+selector = "CallExpression[callee.name='forwardRef']"
+message = "forwardRef papers over two modules that import each other. Move what both need into a third module."
+
+[[eslint.selectors]]
+selector = "Decorator[expression.callee.name=/^(Res|Response)$/]:not(:has(Property[key.name='passthrough'][value.value=true]))"
+message = "Taking the response object turns off interceptors and the return value. Return the value, or pass { passthrough: true }."
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["@darraghor/eslint-plugin-nestjs-typed"]

package/configurations/framework/nestjs/rules/NESTJS.md

@@ -0,0 +1,44 @@
+# NestJS
+
+These rules cover NestJS modules, controllers, providers, validation, configuration, and tests.
+
+## Request handling
+
+- Return the documented HTTP status. Do not report a failed operation as a successful response.
+- Validate body, query, and route parameters before using them. Configure `ValidationPipe`
+  transformation and unknown-field handling for the declared input contract.
+- Do not expose password hashes, tokens, or internal fields in responses.
+
+## Providers and lifecycle
+
+- Register each provider with its intended owner. Repeated registration can create distinct instances.
+- Request-scoped dependencies propagate request scope to their consumers. Check lifetime and
+  resource costs before selecting that scope.
+- Close connections and timers through the application lifecycle, such as `OnModuleDestroy`.
+
+## Configuration and security
+
+- Fail startup when required configuration has missing or malformed values.
+- Use guards for route authorization. Enforce additional permissions at each protected operation
+  when one request performs several operations or the service has non-HTTP callers.
+- Guards run before pipes. Do not assume guard inputs have passed DTO transformation or validation.
+- Set request-size limits, security headers, and rate limits for the exposed application.
+
+## Feature organization
+
+<!-- level: all -->
+
+- Give each feature one module and export only providers consumed by other features.
+- Inject dependencies through constructors instead of constructing them inside consumers.
+- Define the versioning contract before publishing a public API.
+- Keep request DTOs distinct from persistence entities and map between them explicitly.
+
+## Tests
+
+- Use `Test.createTestingModule` and `overrideProvider` to isolate service dependencies.
+- Exercise HTTP behavior with the real pipes, guards, and filters.
+- Do not mock the class under test or assert on private methods.
+- Close test applications in teardown.
+
+See Nest's [response handling](https://docs.nestjs.com/controllers) and
+[authorization guidance](https://docs.nestjs.com/security/authorization).

package/configurations/framework/nextjs/eslint-presets.json

@@ -0,0 +1,73 @@
+{
+    "recommended": {
+        "package": "@next/eslint-plugin-next",
+        "version": "16.3.8",
+        "source": "configs.core-web-vitals",
+        "blocks": [
+            {
+                "parser": false,
+                "rules": {
+                    "@next/next/google-font-display": "warn",
+                    "@next/next/google-font-preconnect": "warn",
+                    "@next/next/next-script-for-ga": "warn",
+                    "@next/next/no-async-client-component": "warn",
+                    "@next/next/no-before-interactive-script-outside-document": "warn",
+                    "@next/next/no-css-tags": "warn",
+                    "@next/next/no-head-element": "warn",
+                    "@next/next/no-html-link-for-pages": "error",
+                    "@next/next/no-img-element": "warn",
+                    "@next/next/no-location-assign-relative-destination": "warn",
+                    "@next/next/no-page-custom-font": "warn",
+                    "@next/next/no-styled-jsx-in-document": "warn",
+                    "@next/next/no-sync-scripts": "error",
+                    "@next/next/no-title-in-document-head": "warn",
+                    "@next/next/no-typos": "warn",
+                    "@next/next/no-unwanted-polyfillio": "warn",
+                    "@next/next/inline-script-id": "error",
+                    "@next/next/no-assign-module-variable": "error",
+                    "@next/next/no-document-import-in-page": "error",
+                    "@next/next/no-duplicate-head": "error",
+                    "@next/next/no-head-import-in-document": "error",
+                    "@next/next/no-script-component-in-head": "error"
+                }
+            }
+        ]
+    },
+    "refresh": {
+        "package": "eslint-plugin-react-refresh",
+        "version": "0.5.7",
+        "source": "configs.next",
+        "blocks": [
+            {
+                "parser": false,
+                "rules": {
+                    "react-refresh/only-export-components": [
+                        "error",
+                        {
+                            "allowExportNames": [
+                                "experimental_ppr",
+                                "dynamic",
+                                "dynamicParams",
+                                "revalidate",
+                                "fetchCache",
+                                "runtime",
+                                "preferredRegion",
+                                "maxDuration",
+                                "metadata",
+                                "generateMetadata",
+                                "viewport",
+                                "generateViewport",
+                                "generateImageMetadata",
+                                "generateSitemaps",
+                                "generateStaticParams",
+                                "instant",
+                                "contentType",
+                                "size"
+                            ]
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+}

package/configurations/framework/nextjs/manifest.toml

@@ -0,0 +1,119 @@
+route_files = ["page", "layout", "template", "default", "loading", "error", "not-found", "global-error", "route", "middleware", "proxy"]
+allowed_words = ["Next.js"]
+generated = ["next-env.d.ts"]
+
+[[naming.override]]
+paths = ["**/app/**", "**/pages/**"]
+categories = ["files"]
+allowed_names = ["instrumentation", "sitemap", "robots", "manifest", "opengraph-image", "icon", "apple-icon", "_app", "_document", "_error", "404", "500"]
+reason = "Next.js names these files."
+
+[[naming.override]]
+paths = ["**"]
+languages = ["typescript", "javascript"]
+categories = ["functions", "methods", "variables"]
+allowed_names = ["getStaticProps", "getServerSideProps", "generateMetadata", "generateStaticParams", "generateViewport"]
+reason = "Next.js discovers these data and metadata exports by name."
+
+[configuration]
+title = "Next.js"
+requires = ["typescript", "react", "react-dom"]
+suggests = ["css"]
+description = "A Next.js app: the framework and hooks rules of ESLint, and server code marked as server only. Route segments serve one thing, and the configuration turns no build check off."
+
+[detect]
+dependencies = ["next"]
+
+[files]
+paths = ["**/next.config.js", "**/next.config.mjs", "**/next.config.ts"]
+
+[[tool]]
+name = "next"
+system = true
+min_version = "15.5.0"
+version_command = ["--version"]
+
+[[tool]]
+name = "@next/eslint-plugin-next"
+rule_prefix = "@next/next"
+kind = "library"
+version = "16.3.8"
+npm = "@next/eslint-plugin-next"
+
+[[check]]
+name = "tsc"
+tool = "next"
+example = "The TypeScript declaration `const count: number = \"one\";` reports an incompatible assignment. Correct it to `const count: number = 1;` when the contract requires a number."
+level = "recommended"
+stage = "push"
+runs = "scope"
+instead_of = "typescript/tsc"
+summary = "Has Next.js write its types, then type-checks the app with the strict compiler options."
+why = "A fresh clone holds no next-env.d.ts and no route types, so a plain tsc run fails on imports the framework resolves."
+help = "Read the first error tsc prints and fix that file; later errors are often the same mistake."
+
+[[check]]
+name = "build"
+tool = "next"
+example = "A Next.js page importing a nonexistent component fails the project build. Restore the component or correct the import path and rerun the configured build."
+level = "all"
+stage = "push"
+runs = "scope"
+needs = ["build"]
+summary = "Builds the app with next build at all when its scope contains an app or pages tree."
+why = "Some mistakes show only at build time: a server import in a client file, or a page that cannot be prerendered."
+help = "Run next build and read the first error it prints."
+
+[check.files]
+paths = ["**/app/**", "**/pages/**"]
+
+[[check]]
+name = "route-segments"
+example = "A Next.js segment containing both `page.tsx` and `route.ts` reports conflicting route ownership. Move the route handler into a separate segment, such as `api`, and update its callers."
+level = "recommended"
+stage = "commit"
+runs = "once"
+summary = "Checks that no route segment holds both a page and a route handler."
+why = "This commit check finds route conflicts before next build and also runs at recommended, where the build check does not."
+help = "Move the route handler into a segment of its own, such as an api folder."
+
+[[check]]
+name = "next-config"
+example = "Setting `typescript.ignoreBuildErrors` to `true` in Next.js configuration reports a disabled type gate. Remove the switch and correct the type errors before building."
+level = "recommended"
+stage = "commit"
+runs = "once"
+summary = "Checks that the framework configuration turns no build check off and puts no secret into the client environment."
+why = "A build that ignores lint and type errors ships them, and a key under env is readable by every visitor."
+help = "Remove the switch, and read the secret on the server."
+
+[[check]]
+name = "version-pairs"
+example = "Different installed versions of `next` and its lint package report an alignment finding. Install the same version of both and update the lockfile with the package manager."
+level = "recommended"
+stage = "commit"
+runs = "once"
+summary = "Checks that Next.js and its lint packages use the same installed version."
+why = "A lint package a version behind flags what the framework allows and allows what it removed."
+help = "Move both packages to the same version."
+
+[eslint]
+all_level_rules = ["@next/next/next-script-for-ga", "@next/next/no-html-link-for-pages", "@next/next/no-img-element", "@next/next/no-page-custom-font"]
+
+[eslint.presets.recommended]
+package = "@next/eslint-plugin-next"
+source = "configs.core-web-vitals"
+
+[eslint.presets.refresh]
+package = "eslint-plugin-react-refresh"
+source = "configs.next"
+
+[[eslint.rules_off]]
+rules = ["gspot/no-trivial-files"]
+reason = "Next.js discovers route files by name, so each file can hold one export in its own folder."
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["@next/eslint-plugin-next"]

package/configurations/framework/nextjs/rules/NEXTJS.md

@@ -0,0 +1,43 @@
+# Next.js
+
+Preserve the project's router, installed Next.js and React versions, runtime, and deployment
+adapter. App Router guidance applies only to App Router routes.
+
+## Server and client ownership
+
+Keep privileged operations and credentials on the server. Send only authorized fields to the
+browser. That includes query hydration and Server Component props. A hidden control, type, or filename
+does not control access. A client entry includes its imports in the client graph; keep it small
+and compose server-rendered children into it.
+
+Validate and authorize every mutation at its server entry. Routes, actions, and RPC procedures
+share the same domain operation. Initial server reads do not HTTP-fetch the application's own
+Route Handler. Rendering, `GET` requests, and prefetching perform no writes.
+
+See [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components).
+
+## Loading and failures
+
+Put a loading boundary around the section that waits. Keep useful content mounted during refresh,
+and reset pending state when the selected resource changes. Start independent work early without
+moving protected reads before authorization.
+
+Decide status, headers, cookies, redirects, and not-found behavior before streaming commits the
+response. Preserve framework control-flow exceptions. Check direct load, client navigation,
+refresh, Back, and failed prefetch; those paths need not share the same state.
+
+See [streaming](https://nextjs.org/docs/app/guides/streaming).
+
+## Cache contracts
+
+Check whether the project enables Cache Components before choosing APIs. Above a cached operation,
+state who may read it, its key, lifetime, and invalidation path. Include identity, tenant, locale,
+filters, and permissions where they affect results; session tokens stay out of keys.
+
+Default private data to uncached until an isolation design exists. Never let a cached decision
+retain revoked access. Clear private browser caches on logout. Invalidate after the write commits
+and before a terminating redirect; a failed refresh must not retry the committed write.
+Next.js and a client query cache need separate reconciliation.
+
+See [caching](https://nextjs.org/docs/app/getting-started/caching)
+and [revalidation](https://nextjs.org/docs/app/getting-started/revalidating).