@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/general/structure/manifest.toml

@@ -0,0 +1,70 @@
+[configuration]
+title = "Structure"
+always_selected = true
+description = "The structural rules no standard linter ships, over every language: wrappers, barrels, lone files, and the size limits."
+
+[files]
+languages = true
+
+[[check]]
+name = "lone-files"
+example = "With the TypeScript configuration at level `all`, `feature/only.ts` reports `lone-file` when it is the folder's only code file. Move it beside related files and update references, or keep the folder when a second substantial file belongs to that feature. Adding `feature/second.ts` makes this folder contain two code files."
+runs = "scope"
+level = "all"
+stage = "commit"
+summary = "Finds a folder that holds one code file and nothing else."
+why = "A folder of one file adds a level to every path and promises siblings that never arrive."
+help = "Move the file up beside its neighbors, or use gspot ignore structure/lone-files with paths and a reason."
+
+[[check]]
+name = "shared-prefixes"
+example = "Sibling files `asset-card.ts`, `asset-list.ts`, and `asset-row.ts` share a repeated prefix. Move them into `asset/` with names `card.ts`, `list.ts`, and `row.ts`, then update imports."
+runs = "scope"
+level = "all"
+stage = "commit"
+summary = "Finds sibling files that share a name prefix, like asset-card, asset-list and asset-row in one folder."
+why = "Files that share a prefix are one concept split by suffix; they belong in a folder named after the prefix."
+help = "Move the files into a folder named after the shared prefix, or allow the set with a reason."
+
+[[check]]
+name = "file-folder-clashes"
+example = "Sibling entries `report.ts` and `report/` have the same stem and report a collision. Rename the file or directory after its distinct responsibility and update every reference."
+runs = "scope"
+level = "all"
+stage = "commit"
+summary = "Finds a file and a folder in the same place with the same stem, like turn.ts beside turn/."
+why = "An import of ./turn names both, and a reader cannot tell which one loads."
+help = "Rename the file or the folder so their stems differ."
+
+[[check]]
+name = "file-lines"
+example = "A Python, Bash, or SQL source file above its language's code-line ceiling reports its count. Split independent responsibilities into their owners and rerun the check."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".sh", ".bash", ".zsh", ".bats", ".py", ".pyi", ".sql", ".pgsql", ".psql"], tags = ["shebang:shell"], kinds = ["source"] }
+summary = "Checks source code lines against each language's ceiling."
+why = "A long file hides independent responsibilities from the reader."
+help = "Split the file by its responsibility, or raise its limits.`<language>`.file_lines with a reason."
+
+[[check]]
+name = "trivial-functions"
+example = "A Bash function that only calls another function reports its declaration. Inline that call into its callers and remove the forwarding function."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+summary = "Finds functions with too few statements and files that only forward to other code."
+why = "A function of one statement makes the reader jump for nothing."
+help = "Inline a forwarding function at its calls and delete it. Split independent statements into the files that use them."
+
+[[check]]
+name = "env-reads"
+example = "A Python file outside architecture.roles.environment_readers that reads os.environ reports that read. Move it into a declared environment reader and pass its value to callers."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+summary = "Finds environment reads outside the files listed in architecture.roles.environment_readers."
+why = "Environment reads spread through the code hide which settings a program needs."
+help = "Move the environment read into a file listed in architecture.roles.environment_readers, then pass the value to callers."

package/configurations/infrastructure/ansible/manifest.toml

@@ -0,0 +1,33 @@
+[configuration]
+title = "Ansible"
+description = "Ansible playbooks, roles, and collections checked by ansible-lint."
+
+[files]
+paths = ["**/ansible.cfg", "**/galaxy.yml", "**/requirements.yml", "**/roles/*/tasks/main.yml"]
+
+[[tool]]
+name = "ansible-lint"
+version = "26.8.0"
+min_version = "24.0.0"
+pypi = "ansible-lint"
+mise = "pipx:ansible-lint"
+brew = "ansible-lint"
+builds = ["macos", "linux"]
+
+[[tool_file]]
+target = ".gspot/config/ansible-lint.yml"
+tool = "ansible-lint"
+per_scope = true
+
+[[check]]
+name = "ansible-lint"
+example = "A task using `ansible.builtin.command: systemctl restart nginx` reports `command-instead-of-module`. Use `ansible.builtin.systemd` with `name: nginx` and `state: restarted` to express the intended service operation."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+tool = "ansible-lint"
+command = ["ansible-lint", "-c", "{tool_file:ansible-lint}", "--offline", "--nocolor", "-f", "pep8", "--profile", "{level:moderate:production}"]
+files = { extensions = [".yml", ".yaml", ".cfg", ".j2"] }
+summary = "Runs the moderate ansible-lint profile at recommended and production at all, beside each ansible.cfg or at the selected scope root."
+why = "A playbook runs as root on production hosts, and a task that is not idempotent changes them on every run."
+help = "Change the task the way the rule says. Turn one rule off with gspot ignore ansible/ansible-lint --rule `<id>` --reason \"`<why>`\"."

package/configurations/infrastructure/docker/manifest.toml

@@ -0,0 +1,127 @@
+prefix_collisions = { prefixes = ["docker"] }
+
+allowed_words = ["Docker", "Trivy"]
+[configuration]
+title = "Docker"
+description = "Dockerfiles and Compose files: hadolint, a Compose file that parses, an ignore file beside every Dockerfile, and Trivy over the configuration."
+
+[detect]
+paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml", "!**/*.dockerignore"]
+
+[files]
+paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml", "**/.dockerignore", "**/*.dockerignore"]
+
+[[tool]]
+name = "hadolint"
+version = "2.14.0"
+mise = "hadolint"
+brew = "hadolint"
+github = { name = "hadolint/hadolint", version = "v2.14.0" }
+scoop = "hadolint"
+[[tool.replace]]
+file = ".hadolint.yaml"
+shared = false
+
+[[tool.replace]]
+file = ".hadolint.yml"
+shared = false
+
+[[tool]]
+name = "trivy"
+version = "0.69.3"
+mise = "trivy"
+brew = "trivy"
+github = { name = "aquasecurity/trivy", version = "v0.69.3" }
+[[tool.replace]]
+file = "trivy.yaml"
+shared = false
+
+[[tool.replace]]
+file = ".trivyignore"
+shared = false
+
+[[tool]]
+name = "docker"
+install_hint = "install Docker Desktop or the docker engine"
+system = true
+
+[[tool_file]]
+target = ".gspot/config/hadolint.yml"
+tool = "hadolint"
+per_scope = true
+rule_keys = ["ignored"]
+
+[[tool_file]]
+target = ".gspot/config/trivy.yml"
+tool = "trivy"
+per_scope = true
+
+[[tool_file]]
+source = "trivyignore"
+target = ".gspot/config/trivyignore"
+tool = "trivy"
+per_scope = true
+
+[[check]]
+name = "hadolint"
+example = "The instruction `FROM node:latest` reports DL3007 because the tag changes over time. Select a reviewed, explicit version tag or digest and rerun."
+level = "recommended"
+stage = "commit"
+command = ["hadolint", "--no-color", "--config", "{tool_file:hadolint}", "{files}"]
+files = { paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "!**/*.dockerignore"] }
+output = { format = "regex", pattern = "^(?<file>.+?):(?<line>\\d+) (?<rule>[A-Z]+\\d+) [a-z]+: (?<message>.*)$" }
+summary = "Lints every Dockerfile, and runs ShellCheck over its RUN lines."
+why = "An unpinned base image or a cache left in a layer makes a build nobody can repeat and an image larger than it needs to be."
+help = "Change the instruction the way the rule says. Turn one rule off with gspot ignore docker/hadolint --rule `<id>` --reason \"`<why>`\"."
+
+[[check]]
+name = "compose"
+example = "A Compose service with an unknown key such as `bogus` fails configuration validation. Remove the key or replace it with the supported setting for the intended behavior."
+level = "recommended"
+stage = "push"
+needs = ["docker"]
+tool = "docker"
+runs = "scope"
+command = ["docker", "compose", "-f", "{file}", "config", "--quiet", "--no-env-resolution"]
+files = { paths = ["**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml"] }
+output = { format = "lines" }
+summary = "Asks Docker Compose to parse every Compose file, which needs no running daemon."
+why = "A Compose file that is valid YAML can still name a key Compose refuses, and the first person to learn that is deploying."
+help = "Read the message Compose prints; it names the key and the service."
+
+[[check]]
+name = "dockerignore"
+example = "A Dockerfile without a neighboring `.dockerignore` reports the missing context exclusions. Add `.dockerignore` with the required entries named in the finding, such as `.git` and dependency directories."
+level = "recommended"
+stage = "commit"
+runs = "once"
+summary = "Checks that an ignore file sits beside every Dockerfile and keeps the git folder, installed dependencies, and environment files out of the build."
+why = "Without it the whole folder goes to the daemon, and copying the folder puts the history and the secrets into the image."
+help = "Add a .dockerignore beside the Dockerfile with the entries the message names."
+
+[[check]]
+name = "trivy-config"
+example = "A Dockerfile whose final application stage runs as root can report a container-security finding. Create an unprivileged user, grant it only required file access, and select it with `USER` before running the application."
+level = "recommended"
+stage = "push"
+runs = "scope"
+run_in_copy = true
+command = ["trivy", "config", "--misconfig-scanners", "dockerfile", "--quiet", "--skip-check-update", "--config", "{tool_file:trivy}", "--ignorefile", "{tool_file:trivyignore}", "--exit-code", "10", "--format", "sarif", "{root}"]
+tool = "trivy"
+exit_codes = [10]
+output = { format = "sarif" }
+summary = "Scans Dockerfiles for HIGH and CRITICAL misconfigurations, including a root user and exposed secrets."
+why = "A container that runs as root turns any bug in the service into control of the container."
+help = "Change the file the way the message says. Accept one advisory with gspot ignore docker/trivy-config --rule `<id>` --reason \"...\"."
+
+[[check]]
+name = "trivy-image"
+example = "A configured image containing a package with a known advisory reports that advisory. Move to a reviewed image version containing the package fix, then rerun the image scan. Results depend on the advisory database and available image."
+level = "recommended"
+stage = "manual"
+runs = "scope"
+needs = ["docker"]
+tool = "trivy"
+summary = "Scans every image a Compose file names for known vulnerabilities in its packages."
+why = "A base image carries hundreds of packages, and their advisories arrive after the image was chosen."
+help = "Move to a newer tag of the image. Accept one advisory with gspot ignore docker/trivy-image --rule `<id>` --reason \"...\"."

package/configurations/infrastructure/docker/rules/DOCKER.md

@@ -0,0 +1,135 @@
+# Docker
+
+## Image inputs
+
+Select a base image that supports the application's runtime, target architecture, native libraries,
+and certificate requirements. Tags can change, so pin a reviewed digest when the build requires
+immutable input, and keep an update process for security fixes: a digest never patches itself.
+
+Use a supported runtime release. For native modules, keep the build and runtime operating system,
+libc, and architecture compatible. Alpine, Debian, and distroless images have different runtime
+and operational requirements; no single variant fits every application.
+
+## Build and runtime stages
+
+Build-only compilers, test dependencies, and package caches stay out of the final image. It keeps
+interpreted source, declared debug artifacts, and any other file the runtime reads.
+Private source maps stay out of publicly served assets. When compilation or dependency preparation
+needs tools the runtime does not, a multi-stage build copies only the runtime inputs into the final
+stage. Host `node_modules` never enter a Linux image.
+
+This npm example assumes a `build` task that writes `dist/main.js`, a committed lockfile, and
+Node.js 24; a release build that requires immutable input pins the reviewed digest.
+
+```dockerfile
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+FROM node:24-bookworm-slim AS dependencies
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+FROM node:24-bookworm-slim AS runtime
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --chown=node:node package.json ./
+COPY --from=dependencies --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+USER node
+CMD ["node", "dist/main.js"]
+```
+
+Use the package manager the project declares; for Bun, its pinned version with
+`bun install --frozen-lockfile`, adding `--production` for runtime dependencies. The final image
+holds a package-manager binary only when the runtime uses it. A statically linked `server` built
+for the target platform needs no package manager or shell, only the certificates, time-zone data,
+or other runtime files it reads.
+
+```dockerfile
+FROM scratch
+COPY server /server
+USER 65532:65532
+ENTRYPOINT ["/server"]
+```
+
+## Package installation and downloads
+
+hadolint reports unpinned images and packages, apt cleanup, `ADD` for local files, and shell-form
+commands. Review these additional requirements:
+
+- Install application dependencies from the declared lockfile without updating it during the build.
+- Refresh repository metadata and install packages in the same `RUN`, so cached metadata cannot
+  select an unintended version.
+- Refresh base images for operating-system fixes. A targeted package upgrade needs an explicit
+  dependency change, never an unbounded distribution upgrade in every build.
+- Verify a downloaded executable's digest or signature before installing it.
+- Remove installation-only files and caches in the layer that creates them.
+
+### Dockerfile organization
+
+<!-- level: all -->
+
+Put stable build inputs before frequently changing application source when that improves cache
+reuse. Put substantial shell behavior in an existing script. Keep the final image's user,
+working directory, environment, and startup command in documented locations. Do not add a wrapper script
+for a command the container can run directly.
+
+## Build context and ignore files
+
+The context holds only the files the build needs, and `.dockerignore` changes with every
+Dockerfile that uses it. A deny-by-default context suits a small, stable input set.
+
+- Never exclude `dist`, generated dependency exports, or build scripts by name alone: a build that
+  copies verified prebuilt output needs it. Every `COPY` source survives the ignore rules.
+
+## Build secrets
+
+Use BuildKit secret mounts for private registry authentication and other build credentials.
+Read the secret only inside the `RUN` instruction that requires it. Copying it into a layer keeps
+it in image history even if a later layer removes it.
+
+## Shell and process behavior
+
+Use the shell syntax actually selected for `RUN`; the default shell does not run Bash. A required
+entrypoint script validates configuration and uses `exec` for its final handoff. A documented
+process supervisor forwards signals and reaps its children, and no init wrapper hides missing
+shutdown behavior in the application.
+
+The application's shutdown limit fits the orchestrator's grace period.
+
+## Runtime
+
+- Durable state lives in explicit volumes or external storage. Environment-specific values arrive
+  at runtime. A production Node.js
+  service sets `NODE_ENV=production` where the runtime expects it.
+- Expose only the required ports, and bind private local services to localhost. Never add Linux
+  capabilities, public debug ports, or disabled TLS verification to make a build or service work.
+- Resource limits fit the deployment and leave room for native memory, buffers, and runtime
+  overhead beyond a language heap limit. Ask the user for memory measurements before changing a limit
+  when the task provides none.
+
+## Compose
+
+Compose declares the wiring: ports, volumes, secrets, resource limits, health checks, restart
+policy, and dependencies. Behavior stays in the application. `depends_on` orders startup, with the
+health condition when a service needs another one ready. A production container never bind-mounts
+development source or host dependencies.
+
+## Verification
+
+Do not build or run images unless the user asks or the repository's checks require it. Give the user a list of items to check: the image's user, command, runtime files, permissions, exposed ports, startup,
+readiness, shutdown, and resource limits. Image documentation names the current build arguments,
+supported platforms, runtime environment, and artifact paths.
+
+## References
+
+| Topic         | Primary source                                                                        |
+| ------------- | ------------------------------------------------------------------------------------- |
+| Builds        | [Docker build best practices](https://docs.docker.com/build/building/best-practices/) |
+| Build secrets | [Secret mounts](https://docs.docker.com/reference/dockerfile/#run---mounttypesecret)  |

package/configurations/infrastructure/docker/trivyignore

@@ -0,0 +1,2 @@
+# This file stops Trivy from reading the repository .trivyignore.
+# Accept a finding with gspot ignore docker/trivy-config and a reason.

package/configurations/infrastructure/github-actions/manifest.toml

@@ -0,0 +1,76 @@
+allowed_words = ["GitHub"]
+[configuration]
+title = "GitHub Actions"
+description = "GitHub Actions workflows: actionlint for syntax and expressions, pinact for the commits actions are pinned to, and zizmor for security audits."
+
+[files]
+paths = ["**/.github/workflows/*.{yml,yaml}", "**/action.{yml,yaml}"]
+
+[[tool]]
+name = "actionlint"
+version = "1.7.12"
+mise = "actionlint"
+brew = "actionlint"
+github = { name = "rhysd/actionlint", version = "v1.7.12" }
+
+[[tool]]
+name = "shellcheck"
+
+[[tool]]
+name = "pinact"
+crash_pattern = '(?:ERROR|FATAL).*?(?:\b(?:401|403|408|429|5[0-9]{2})\b|dial tcp|TLS handshake|x509:|context deadline exceeded|connection reset|no such host)'
+version = "5.0.0"
+mise = "pinact"
+brew = "pinact"
+github = { name = "suzuki-shunsuke/pinact", version = "v5.0.0" }
+
+[[tool]]
+name = "zizmor"
+version = "1.30.1"
+mise = "zizmor"
+pypi = "zizmor"
+brew = "zizmor"
+cargo = "zizmor"
+
+[[tool_file]]
+source = "zizmor.yml"
+target = ".gspot/config/zizmor.yml"
+tool = "zizmor"
+
+[[check]]
+name = "actionlint"
+example = "A workflow using an unknown expression context such as `${{ unknown.value }}` reports an actionlint error. Replace it with a supported context and property for that workflow location."
+level = "recommended"
+stage = "commit"
+tool = ["actionlint", "shellcheck"]
+command = ["actionlint", "-no-color", "{files}"]
+files = { paths = ["**/.github/workflows/*.{yml,yaml}"] }
+exit_codes = [1]
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): (?<message>.*?) \\[(?<rule>[a-z-]+)\\]$" }
+summary = "Checks every GitHub Actions workflow with actionlint: syntax, expressions, action inputs, and shell steps."
+why = "A workflow error surfaces on the first push after the change, in CI, where it costs a round trip."
+help = "Fix the line actionlint names."
+
+[[check]]
+name = "pinact"
+example = "An action reference such as `actions/checkout@v4` without a full commit pin reports an unpinned action. Resolve a reviewed release to its full commit SHA and record the matching version comment beside the pin."
+level = "recommended"
+stage = "push"
+needs = ["network"]
+command = ["pinact", "run", "--verify-comment", "--check", "{files}"]
+output = { format = "lines" }
+summary = "Checks that each GitHub action has a full commit pin that exists and a matching version comment."
+why = "A tag can move between runs, a nonexistent commit prevents the workflow from starting, and a wrong version comment hides the intended release."
+help = "Replace the invalid action pin with a verified commit and its matching version comment."
+
+[[check]]
+name = "zizmor"
+example = "A workflow interpolating pull-request text directly into a shell command can report a template-injection audit. Pass the text through a step environment variable and quote its expansion instead of interpolating it into shell code."
+level = "recommended"
+stage = "commit"
+command = ["zizmor", "--offline", "--no-progress", "--format", "github", "--config", "{tool_file:zizmor}", "{files}"]
+exit_codes = [11, 12, 13, 14]
+output = { format = "regex", pattern = "^::(?:warning|error|notice) file=(?<file>[^,]+),line=(?<line>\\d+),title=(?<rule>[^:]+)::(?<message>.*)$" }
+summary = "Audits GitHub Actions workflows and composite actions with zizmor for template injection, excessive permissions, and dangerous triggers."
+why = "A workflow runs with the repository's credentials; an injectable expression can hand them to a stranger."
+help = "Apply the fix zizmor names, or turn one audit off with gspot ignore github-actions/zizmor --rule `<audit>` --reason \"`<why>`\"."

package/configurations/infrastructure/github-actions/rules/GITHUB-ACTIONS.md

@@ -0,0 +1,43 @@
+# GitHub Actions
+
+## Workflow shape
+
+- Every job has `timeout-minutes`. Every workflow that can run twice for one ref has a
+  `concurrency` group with `cancel-in-progress` for pull requests.
+- Pin a runner image such as `ubuntu-24.04` for each job. Do not use `ubuntu-latest`.
+- No `continue-on-error` without a reason comment. Required failures must fail the job.
+- Upload diagnostics after failed checks with an explicit status condition. Deployments and
+  release publication require successful prerequisites.
+
+## Repository actions and secrets
+
+- Reference first-party actions from the repository by path.
+- Read secrets through `${{ secrets.NAME }}` into an `env` for the one step that needs them.
+  Never write them to files that outlive the step.
+
+## Scripts
+
+- Declare the shell required by the script. The explicit Bash shell in GitHub Actions enables `-e` and
+  `pipefail`, but does not enable `-u`. Enable required options and validate inputs explicitly.
+- Key caches on the lockfile hash and the runtime version. Restore keys never match a
+  different lockfile.
+
+## Outputs
+
+- Artifacts and summaries name the job and the ref. Set retention explicitly.
+- Give deploy credentials only to the workflow that deploys. Run it on a protected
+  environment with a reviewer.
+
+See [the GitHub shell configuration](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell)
+for the command each runner uses.
+
+## Workflow organization
+
+<!-- level: all -->
+
+- Give each workflow one purpose, such as checks, release publication, or deployment.
+- Call existing task-runner commands instead of copying their implementation into a workflow.
+- Keep substantial logic in scripts that run locally through the task runner and in CI without
+  a prompt. Run the checks their language requires.
+- A verification job changes source only when its task requires formatting or code generation.
+- Write logs and reports to predictable artifact paths.

package/configurations/infrastructure/github-actions/zizmor.yml

@@ -0,0 +1,3 @@
+rules:
+    unpinned-uses:
+        disable: true

package/configurations/infrastructure/nginx/manifest.toml

@@ -0,0 +1,51 @@
+allowed_words = ["nginx"]
+[configuration]
+title = "nginx"
+description = "nginx configuration: gixy for the security mistakes, and the server's own parser in a container for the rest."
+
+[files]
+paths = ["**/nginx.conf", "**/nginx/**/*.conf"]
+
+[[tool]]
+name = "gixy"
+version = "0.2.53"
+pypi = "gixy-ng"
+mise = "pipx:gixy-ng"
+builds = ["macos", "linux"]
+version_pattern = "(\\d+\\.\\d+\\.\\d+)"
+
+[[tool]]
+name = "docker"
+
+[[tool]]
+name = "openssl"
+system = true
+
+[[tool_file]]
+target = ".gspot/config/gixy.cfg"
+tool = "gixy"
+rule_keys = ["skips"]
+
+[[check]]
+name = "gixy"
+example = "A location matching `/proxy/(.*)` with `proxy_pass http://$1` lets the request choose the destination and reports `ssrf`. Remove the request-controlled proxy destination and use the intended fixed upstream, or remove the proxy operation when the endpoint only needs to return a response."
+level = "recommended"
+stage = "commit"
+command = ["gixy", "--config", "{tool_file:gixy}", "--format", "json", "{file}"]
+output = { format = "json", fields = { file = "path", line = "line", rule = "plugin", message = "summary" } }
+summary = "Reads every nginx file for the mistakes that open a server: request forgery, path traversal through alias, header injection, a disclosed version."
+why = "These mistakes parse, serve traffic, and look like any other location block until somebody uses them."
+help = "Change the block the way the rule's page says. Turn one rule off with gspot ignore nginx/gixy --rule `<name>` --reason \"`<why>`\"."
+
+[[check]]
+name = "config-test"
+example = "The line `invalid_directive on;` fails the native configuration test with `nginx -t`. Remove the unknown directive or replace it with the intended supported directive, such as `listen 443 ssl;` in the configured TLS server. Rerun with the configured deployment image available."
+level = "recommended"
+stage = "push"
+runs = "scope"
+needs = ["docker"]
+tool = "docker"
+files = { filenames = ["nginx.conf"] }
+summary = "Validates each main configuration inside the nginx image and records the files nginx parsed. It mounts a throwaway certificate and resolves upstream names."
+why = "Only nginx knows whether nginx accepts the file, and the other place to learn it is the restart in production."
+help = "Read the line nginx names. Set tools.nginx.image to the image the deployment runs."

package/configurations/infrastructure/nginx/rules/NGINX.md

@@ -0,0 +1,38 @@
+# `nginx`
+
+## Edge responsibilities
+
+- nginx must not encode product authorization or feature behavior.
+
+## Configuration
+
+- One `server` block per hostname. Redirect the plain-HTTP server to HTTPS and every alias to
+  the canonical host.
+- TLS: `ssl_protocols TLSv1.2 TLSv1.3`, a modern cipher list from the platform's generator,
+  and an explicit session-ticket policy. Enable Online Certificate Status Protocol (OCSP) stapling only when the certificate issuer
+  supports it and you can verify its response.
+- Put the application's security-header directives in one shared include. Use `always` where a
+  header must also appear on error responses.
+- `client_max_body_size` per location, matching the application route limits, with a small
+  default.
+- Set explicit `proxy_read_timeout`, `proxy_connect_timeout`, and `send_timeout` values that align
+  with the application's shutdown grace period.
+- Name rate-limit zones for what they protect, such as `zone=login_attempts`, and size them with a
+  comment stating the budget.
+- Set proxy headers according to the upstream trust contract. Overwrite untrusted client
+  values where required. The application trusts forwarding metadata only from approved proxies.
+- Use immutable caching only for content-addressed assets. Give mutable resources a cache
+  lifetime and revalidation policy consistent with their update process.
+- Keep configuration in the repository, lint it before commit, and reload it through the
+  deployment flow, never edited on the host.
+
+## Images
+
+- Pin the nginx image to a full version tag of the variant the project uses, never `nginx:alpine`
+  or `latest`.
+- The image copies the configuration and nothing else. No shell in the entrypoint.
+
+See [nginx TLS configuration](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling)
+for stapling requirements. Certificate authorities can
+[retire OCSP](https://letsencrypt.org/2024/12/05/ending-ocsp); verify issuer support
+before enabling stapling.

package/configurations/infrastructure/openapi/manifest.toml

@@ -0,0 +1,50 @@
+[configuration]
+title = "OpenAPI"
+description = "A committed OpenAPI document: Spectral lints it, and the command that writes it must not change it."
+
+[detect]
+filenames = ["openapi.yaml", "openapi.yml", "openapi.json", "swagger.json", "swagger.yaml"]
+
+[[tool]]
+name = "spectral"
+version = "6.15.0"
+npm = "@stoplight/spectral-cli"
+mise = "npm:@stoplight/spectral-cli"
+
+# Spectral's Ajv plugins must use the same ajv package as Spectral, so the tool project installs one shared ajv.
+
+[[tool]]
+name = "ajv"
+
+[[tool_file]]
+target = ".gspot/config/spectral.yaml"
+tool = "spectral"
+
+[[check]]
+name = "spectral"
+example = "An OpenAPI document whose operation references an undefined schema reports a validation finding. Define the schema or correct the reference in the source that produces the document, then regenerate it."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+tool = "spectral"
+cwd = "root"
+command = ["spectral", "lint", "--ruleset", "{tool_file:spectral}", "--format", "text", "{setting:openapi.document}"]
+when = { setting = "openapi.document" }
+output = { format = "regex", pattern = '^(?<file>.+):(?<line>\d+):(?<column>\d+) (?:error|warning) (?<rule>\S+) "(?<message>.*)"$' }
+files = { extensions = [".yaml", ".yml", ".json"] }
+summary = "Lints the OpenAPI document named in openapi.document with the Spectral OpenAPI rules."
+why = "Clients are written from this document, so an operation with no id or an undefined response becomes somebody's broken client."
+help = "Change the document the way the rule says, or the code that writes it."
+
+[[check]]
+name = "stale-document"
+command = ["{setting:openapi.generate_command}"]
+when = { setting = "openapi.generate_command" }
+generated_paths = [{ path = "{setting:openapi.document}" }]
+example = "A committed OpenAPI document that differs from the configured generator output reports drift. Run the declared generator, inspect the changed document, and retain the corrected output before rerunning."
+level = "recommended"
+stage = "push"
+runs = "scope"
+summary = "Runs the command in openapi.generate_command and fails when it changes the document."
+why = "A committed document that lags the routes describes a service that does not exist."
+help = "Run the command and commit the document it writes."