@ihelpee/prumo-plugin-node-next 0.8.3 → 0.9.0

package/README.md

@@ -9,31 +9,31 @@
 
 > Official Next.js **App Router** architectural invariant plugin for [Prumo](https://www.npmjs.com/package/@ihelpee/prumo) — the deterministic gatekeeper and business guardrails for AI-assisted engineering.
 
-No App Router, a **Server Action é um endpoint HTTP público que se disfarça de função interna** e `"use client"` marca um **entry point de bundle**, não um arquivo. Um agente que gera código por IA escreve a action como se fosse uma chamada interna confiável; o compilador transforma cada `export` de `"use server"` num `POST` alcançável por qualquer um. Este plugin fiscaliza essa fronteira com AST estática pura — **sem boot do Next, sem `react`, sem `next build`**.
+In the App Router, a **Server Action is a public HTTP endpoint disguised as an internal function**, and `"use client"` marks a **bundle entry point**, not a file. An AI code-generation agent writes the action as if it were a trusted internal call; the compiler turns every `"use server"` `export` into a `POST` reachable by anyone. This plugin polices that boundary with pure static AST — **no Next boot, no `react`, no `next build`**.
 
-## Invariantes
+## Invariants
 
-| id | sev. | o footgun | fronteira honesta (o que NÃO pega) |
+| id | sev. | the hidden constructive anti-pattern | the honest boundary (what it does NOT catch) |
 |---|---|---|---|
-| `server-action-mutation-guarded` | error | Server Action / Route Handler de mutação escreve no banco sem re-verificar auth **no próprio corpo, antes da escrita** | leitura pura (`GET`); guard delegado a um DAL `server-only` que faz o auth dentro |
-| `client-boundary-leak-prevented` | error | o grafo do cliente (alcançável de um `"use client"`) importa ORM/cliente de banco, módulo de segredo ou lê `process.env` não-`NEXT_PUBLIC_` | módulo compartilhado sem ORM/segredo; `await import(nomeVariavel)` (limitação declarada) |
-| `server-action-input-validated` | error | Server Action muta estado sem validar input por schema (Zod/Valibot) **antes** do banco | schema valida **shape, não posse** — IDOR é checagem separada, nunca reportada como "seguro" |
-| `middleware-not-sole-auth` | error | autorização sustentada **só** por `middleware.ts`/`proxy.ts`, sem re-verificação nas actions/handlers | endpoints que re-verificam auth dentro do próprio corpo |
-| `next-public-env-not-secret` | error | `NEXT_PUBLIC_*` com nome de segredo (`KEY`/`SECRET`/`TOKEN`/`DATABASE_URL`/...) é inlined no bundle em build time | `NEXT_PUBLIC_*` genuinamente público (ex.: `NEXT_PUBLIC_SITE_URL`) |
+| `server-action-mutation-guarded` | error | A mutating Server Action / Route Handler writes to the database without re-verifying auth **in its own body, before the write** | pure read (`GET`); guard delegated to a `server-only` DAL that does the auth internally |
+| `client-boundary-leak-prevented` | error | the client graph (reachable from a `"use client"`) imports an ORM/database client, a secret module, or reads non-`NEXT_PUBLIC_` `process.env` | shared module without ORM/secret; `await import(variableName)` (declared limitation) |
+| `server-action-input-validated` | error | A Server Action mutates state without validating input via a schema (Zod/Valibot) **before** the database | a schema validates **shape, not ownership** — IDOR is a separate check, never reported as "safe" |
+| `middleware-not-sole-auth` | error | authorization sustained **only** by `middleware.ts`/`proxy.ts`, with no re-verification in the actions/handlers | endpoints that re-verify auth within their own body |
+| `next-public-env-not-secret` | error | a `NEXT_PUBLIC_*` with a secret name (`KEY`/`SECRET`/`TOKEN`/`DATABASE_URL`/...) is inlined into the bundle at build time | a genuinely public `NEXT_PUBLIC_*` (e.g.: `NEXT_PUBLIC_SITE_URL`) |
 
-Compatível com **Next 14 / 15 / 16**: o extractor reconhece `middleware.ts` **e** `proxy.ts` (Next 16 renomeou middleware→proxy) como a mesma classe, e aceita `cookies()` e `await cookies()` (Next 15 assíncrono).
+Compatible with **Next 14 / 15 / 16**: the extractor recognizes `middleware.ts` **and** `proxy.ts` (Next 16 renamed middleware→proxy) as the same class, and accepts both `cookies()` and `await cookies()` (Next 15 async).
 
-## Instalação
+## Installation
 
 ```bash
 pnpm add -D @ihelpee/prumo-plugin-node-next @ihelpee/prumo
-# ou
+# or
 npm install --save-dev @ihelpee/prumo-plugin-node-next @ihelpee/prumo
 ```
 
-## Uso
+## Usage
 
-No `prumo.config.ts` do seu app Next:
+In your Next app's `prumo.config.ts`:
 
 ```ts
 import { defineConfig } from '@ihelpee/prumo';
@@ -49,66 +49,71 @@ export default defineConfig({
 });
 ```
 
-Em `.prumo/invariants/rules.ts`, aplique o preset:
+In `.prumo/invariants/rules.ts`, apply the preset:
 
 ```ts
 import { withWaivers } from '@ihelpee/prumo';
 import { nextPreset } from '@ihelpee/prumo-plugin-node-next';
 
-// Waiver estreito é dívida visível; largo é o gate desligado com nome bonito.
+// A narrow waiver is visible debt; a broad one is the gate switched off with a pretty name.
 export default withWaivers(nextPreset, '.prumo/waivers/legacy.json', [
   'server-action-mutation-guarded',
 ]);
 ```
 
-Ou registre o plugin inteiro (extractor + regras) via contrato:
+Or register the whole plugin (extractor + rules) via the contract:
 
 ```ts
 import next from '@ihelpee/prumo-plugin-node-next';
-// prumo plugin node-next  → mostra o catálogo e o snippet de config
+// prumo plugin node-next  → shows the catalog and the config snippet
 ```
 
-Rode o gate:
+Run the gate:
 
 ```bash
 npx prumo gate
 ```
 
-## Exemplo — o achado que o teste unitário com mock nunca vê
+## Example — the finding a mocked unit test never sees
 
 ```ts
 // app/posts/[id]/page.tsx  (Server Component)
 export default async function PostPage({ params }) {
   const { id } = await params;
   async function deletePost(formData: FormData) {
-    'use server';                                   // ← vira POST público
+    'use server';                                   // ← becomes a public POST
     const postId = String(formData.get('id'));
-    await db.post.delete({ where: { id: postId } }); // ← sem auth(), sem schema
+    await db.post.delete({ where: { id: postId } }); // ← no auth(), no schema
   }
   return <form action={deletePost}>…</form>;
 }
 ```
 
-O teste feliz ("logado → clica → 200") **confirma a crença do agente**. O gate nega:
+The happy-path test ("logged in → clicks → 200") **confirms the agent's belief**. The gate denies it:
 
 ```
 server-action-mutation-guarded  app/posts/[id]/page.tsx:6 deletePost
 server-action-input-validated   app/posts/[id]/page.tsx:6 deletePost
 ```
 
-## Oráculo: a action é um endpoint, não uma função
+## Oracle: the action is an endpoint, not a function
 
-Um teste que `import { deletePost } from '@/app/actions'` e a chama como JS **contorna o POST público** — é espelho, não oráculo, e o `oracle-isolation` do core o marca como tal (não conta para o OII). O oráculo canônico é o **teste negativo**: `POST` na action **sem cookie de sessão** deve falhar. Cookies forjados não valem como evidência.
+A test that does `import { deletePost } from '@/app/actions'` and calls it as JS **bypasses the public POST** — it is a mirror, not an oracle, and the core's `oracle-isolation` flags it as such (it does not count toward the OII). The canonical oracle is the **negative test**: a `POST` to the action **without a session cookie** must fail. Forged cookies do not count as evidence.
 
-## Autor & Maintainer
+## Author & Maintainer
 
 **Alex Gotardi**  
 - 📧 Email: [alexgotardi@gmail.com](mailto:alexgotardi@gmail.com)  
 - 🐙 GitHub: [@alexgotardi](https://github.com/alexgotardi)  
 - 💼 LinkedIn: [linkedin.com/in/alexgotardi](https://www.linkedin.com/in/alexgotardi/)
 
-## Corporate Ownership & License
+---
 
-Copyright © 2026 **IHELPEE TECNOLOGIA LTDA** (<https://ihelpee.com>). Created and authored by [Alex Gotardi](https://github.com/alexgotardi).
+## License & Brand
 
-Licensed under the [Apache License, Version 2.0](https://github.com/ihelpee/prumo/blob/main/LICENSE). Free for commercial and private use; attribution and the [`NOTICE`](https://github.com/ihelpee/prumo/blob/main/NOTICE) file must be preserved. The **"Prumo"** name and logo are trademarks of IHELPEE TECNOLOGIA LTDA and are not licensed under Apache 2.0 — see [Brand Protection](https://github.com/ihelpee/prumo#-corporate-ownership-licensing--brand-protection).
+Copyright © 2026 **IHELPEE TECNOLOGIA LTDA** (<https://ihelpee.com>). All rights reserved.
+Created and authored by [Alex Gotardi](https://github.com/alexgotardi).
+
+Licensed under the [Apache License, Version 2.0](https://github.com/ihelpee/prumo/blob/main/LICENSE) (the "License"); you may not use this file except in compliance with the License. A copy is available at <http://www.apache.org/licenses/LICENSE-2.0>.
+
+The **"Prumo"** name and logo are trademarks of IHELPEE TECNOLOGIA LTDA and are **not** licensed under the Apache 2.0 license.

package/dist/ast.d.ts

@@ -26,7 +26,7 @@ export interface NextFile {
     serverComponents: string[];
     envReads: EnvRead[];
     importsServerOnly: boolean;
-    /** Import dinâmico/require de string literal que casa ORM_PACKAGES (tripwire §7). */
+    /** Import dinâmico/require de string literal que casa ORM_PACKAGES (linha de marcação §7). */
     dynamicOrmImports: string[];
 }
 export interface RouteHandlerInfo {

package/dist/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmC,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5E;;;;;;;GAOG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,oEAAoE;IACpE,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,eAAO,MAAM,UAAU,aAQrB,CAAC;AAmBH,eAAO,MAAM,YAAY,UAexB,CAAC;AAkDF,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CASlD;AA0HD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,QAAQ,CA0H7J;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,SAAS,CAsDnF;AAwBD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,MAAM,CAI1D"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmC,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5E;;;;;;;GAOG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,oEAAoE;IACpE,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,8FAA8F;IAC9F,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,eAAO,MAAM,UAAU,aAQrB,CAAC;AAmBH,eAAO,MAAM,YAAY,UAexB,CAAC;AAkDF,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CASlD;AA0HD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,QAAQ,CA0H7J;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,SAAS,CAsDnF;AAwBD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,MAAM,CAI1D"}

package/dist/rules.d.ts

@@ -12,7 +12,7 @@ export declare const serverActionMutationGuarded: RuleDef;
  * `process.env` não-`NEXT_PUBLIC_`. Reporta a TRILHA para ser acionável.
  *
  * Não pega: módulo compartilhado sem ORM/segredo importado por client.
- * Limitação declarada: `await import(nomeVariavel)` não resolve (tripwire só
+ * Limitação declarada: `await import(nomeVariavel)` não resolve (linha de marcação só
  * para string literal de ORM).
  */
 export declare const clientBoundaryLeakPrevented: RuleDef;

package/dist/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAGb,MAAM,2BAA2B,CAAC;AAsCnC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,SAuB9B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,SA6D9B,CAAC;AAKX;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,SAmB7B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,SAsBxB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,SAoBzB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,UAAU,iDAerB,CAAC;AAEH,eAAO,MAAM,UAAU,EAAE,OAAO,EAAqB,CAAC"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAGb,MAAM,2BAA2B,CAAC;AAuCnC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,SAuB9B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,SA6D9B,CAAC;AAKX;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,SAmB7B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,SAsBxB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,SAoBzB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,UAAU,iDAerB,CAAC;AAEH,eAAO,MAAM,UAAU,EAAE,OAAO,EAAqB,CAAC"}

package/dist/rules.js

@@ -1,5 +1,6 @@
 import { rule, definePlugin, } from '@ihelpee/prumo/invariants';
 import { extractNextModel, isOrmSpecifier, } from './ast.js';
+import pkg from '../package.json' with { type: 'json' };
 /**
  * Invariantes do App Router (spec §2). Os cinco ids são canônicos e
  * congelados: nenhum card filho pode renomeá-los sem voltar à especificação.
@@ -59,7 +60,7 @@ export const serverActionMutationGuarded = rule('server-action-mutation-guarded'
  * `process.env` não-`NEXT_PUBLIC_`. Reporta a TRILHA para ser acionável.
  *
  * Não pega: módulo compartilhado sem ORM/segredo importado por client.
- * Limitação declarada: `await import(nomeVariavel)` não resolve (tripwire só
+ * Limitação declarada: `await import(nomeVariavel)` não resolve (linha de marcação só
  * para string literal de ORM).
  */
 export const clientBoundaryLeakPrevented = rule('client-boundary-leak-prevented')
@@ -222,7 +223,7 @@ export const nextPublicEnvNotSecret = rule('next-public-env-not-secret')
  */
 export const nextPlugin = definePlugin({
     name: 'node-next',
-    version: '0.1.0',
+    version: pkg.version,
     description: 'Next.js App Router invariants: Server Action auth guards, client boundary leaks, input validation, proxy-not-sole-auth, NEXT_PUBLIC secret hygiene.',
     extractors: {
         next: (ctx) => extractNextModel(ctx.root, (ctx.sourceFiles ?? [])),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihelpee/prumo-plugin-node-next",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "type": "module",
   "description": "Next.js App Router plugin for Prumo: Server Action guards, client boundary leaks, and input validation invariants.",
   "author": "Alex Gotardi <alexgotardi@gmail.com> (https://github.com/alexgotardi)",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ihelpee/prumo": "0.8.3",
+    "@ihelpee/prumo": "0.9.0",
     "ts-morph": "^24.0.0"
   }
 }