@semacode/cli 2.3.1 → 3.5.0

package/docs/syntax.md

@@ -87,6 +87,20 @@ impl {
 
 `sema compilar --alvo javascript` defines a generation target. `impl { js: ... }` defines the live-code origin linked to the contract. They are different layers and both are valid.
 
+## Layered `impl` Roles
+
+Layered code (route + service + persistence in the same language) can declare one `impl` per role. Append a supported role to the origin: `rota`, `servico`, `persistencia` or `repositorio`.
+
+```sema
+impl {
+  ts_rota: server.routes.monitores.criarMonitor
+  ts_servico: server.services.monitores.criarMonitor
+  ts_persistencia: server.repositories.monitores.criar
+}
+```
+
+Each origin-plus-role pair must appear at most once; the bare origin (for example `ts`) stays valid for single-layer tasks, and drift resolves every role independently.
+
 ## Small Canonical Lists
 
 - `effects`: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.

package/docs/testing.md

@@ -1,51 +1,150 @@
-# Testing
-
-Public Sema tests should run locally.
-
+# Testing
+
+Public Sema tests should run locally.
+
 Recommended checks:
-
-```bash
-npm run build
-npm run status:check
-npm run repo:verificar-publico
-npm run plugin:testar-codex
-npm run cli:empacotar-publica
-npm run cli:testar-pacote-publico
-node pacotes/cli/dist/index.js --help
-node pacotes/cli/dist/index.js --version
-node pacotes/cli/dist/index.js resumo exemplos/calculadora.sema --micro --json
-node pacotes/cli/dist/index.js validar exemplos/calculadora.sema --json
-node pacotes/cli/dist/index.js testar exemplos/calculadora.sema --alvo dotnet --saida .tmp/testing-dotnet
-node pacotes/cli/dist/index.js testar exemplos/calculadora.sema --alvo cpp --saida .tmp/testing-cpp
-npm run release:preparar-publica
+
+```bash
+npm run build
+npm run status:check
+npm run repo:verificar-publico
+npm run plugin:testar-codex
+npm run cli:empacotar-publica
+npm run cli:testar-pacote-publico
+node pacotes/cli/dist/bin.js --help
+node pacotes/cli/dist/bin.js --version
+node pacotes/cli/dist/bin.js resumo exemplos/calculadora.sema --micro --json
+node pacotes/cli/dist/bin.js validar exemplos/calculadora.sema --json
+node pacotes/cli/dist/bin.js testar exemplos/calculadora.sema --alvo dotnet --saida .tmp/testing-dotnet
+node pacotes/cli/dist/bin.js testar exemplos/calculadora.sema --alvo cpp --saida .tmp/testing-cpp
+npm run release:preparar-publica
 npm run release:verificar-drift
 ```
 
-Focused drift regressions live in:
-
-- `testes/unidade/projeto-carregamento-escopo.test.ts`: a file target loads only itself plus the transitive `use` closure.
-- `testes/integracao/drift-cli-modes.test.ts`: `inspecionar` and `resumo --micro` do not run fresh drift implicitly and do not publish code scores when drift is `none`.
-- `testes/integracao/drift-escopo-io.test.ts`: focused drift never opens unrelated `firecrawl`, training, or SQL dump files; the warm cache performs no source read or AST creation; one changed unit leaves unrelated groups reusable; project scope shares one catalog walk and one physical read per file.
-- `testes/unidade/drift-catalogo-cache.test.ts`: validated catalog snapshots, metadata/content hits, configuration identity invalidation, runtime payload validation, corruption recovery, and realpath containment remain explicit.
-
-Do not require private or sensitive operational material for public test
-evidence. The public-package smoke must also reject the removed authorization
-command, legacy gate markers, any stale billing artifact, secrets, and broken
-encoding in every published document. The plugin smoke must validate the repo
-marketplace, manifest version, installed skill copy, and absence of Sema MCP.
-After push and npm publication, `npm run release:verificar-distribuicao` must
-repeat that installation from the remote `gerlanss/Sema` marketplace and prove
-that GitHub HEAD, the installed skill, and the manifest-declared npm version
-all describe the same release.
+`npm run cli:empacotar-publica` is the only supported package factory. It
+builds a private, per-run stage outside `pacotes/cli`, invokes npm there with
+lifecycle scripts disabled, validates the complete tarball, and publishes the
+final `.tgz` without replacing a different concurrent winner. Running `npm
+pack` directly in the source workspace must fail closed and leave the source
+tree byte-for-byte unchanged.
 
+Packaging regressions must prove rejection of pre-existing source or output
+junctions, zero external writes in those cases, cross-volume publication,
+cleanup after injected faults, concurrent no-replace publication, and a full
+stage sweep for source maps, credentials, environment files, and billing
+artifacts. Post-operation identity checks detect ordinary path swaps, but tests
+must not claim containment against a hostile same-user process racing path
+operations; that stronger guarantee requires native directory-handle-relative
+filesystem primitives that Node.js does not provide cross-platform.
+
+Do not require private or sensitive operational material for public test
+evidence. The public-package smoke must also reject the removed authorization
+command, legacy gate markers, any stale billing artifact, secrets, and broken
+encoding in every published document. The plugin smoke must validate the repo
+marketplace, manifest version, installed skill copy, and absence of Sema MCP.
+After push and npm publication, `npm run release:verificar-distribuicao` must
+repeat that installation from the remote `gerlanss/Sema` marketplace and prove
+that GitHub HEAD, the installed skill, and the manifest-declared npm version
+all describe the same release.
+
 The local public-package smoke installs the generated tarball in an isolated
 sandbox. It must import the root API without executing the CLI, materialize
 nested interactive examples, and execute discovery, interactive schema,
 definition validation, planning, and adapter-protocol validation through the
-installed binary. Passing this smoke proves the local tarball only; it does not
-mean that npm or a GitHub release was published.
+installed binary. Its global-install phase uses an isolated home, prefix, npm
+cache, and user cache; it verifies the absolute launcher with Node.js/npm absent
+from `PATH`, exact skill digests, read-only status, idempotent repair, and zero
+changes to the real home or workspace. On Windows it must resolve `sema.ps1`
+from a restricted `PATH`, invoke `sema-managed.ps1` with the absolute system
+`powershell.exe`, and exercise `sema.cmd` with conventional `cmd.exe` arguments.
+Byte-exact arbitrary argv is proved through the PowerShell entrypoints. Passing this smoke proves
+the local tarball only; it does not mean that npm or a GitHub release was
+published.
+
+The same installed-package smoke must execute root help plus `iniciar --help`,
+`dev --help`, `formatar --help`, `sync-codex --help`, `skill sync --help`, short
+`-h`, and help after unknown arguments. Each text and `--json` invocation runs
+from an empty isolated workspace with an isolated HOME, user cache, plugin
+cache, and npm cache. A recursive content fingerprint before and after every
+invocation must remain identical, and every help path must finish within the
+smoke timeout with exit code `0` and empty stderr.
+
+The purity preload also fails on reads under the isolated workspace, HOME, or
+cache roots, subprocess creation, and network primitives. Module reads from the
+installed package itself remain allowed. The smoke invokes the real installed
+launcher with PATH emptied, so a passing direct `node dist/bin.js` probe alone
+is not accepted as launcher evidence.
+
+JSON help must be one parseable `sema.cli.control/v1` document containing
+exactly `schemaVersion`, `ok`, `kind`, `code`, `message`, and `exitCode`. The
+smoke must also prove a non-zero `UNKNOWN_COMMAND` control response whose
+process status equals `exitCode`, with no stack, absolute path, raw argv, or
+second JSON document. Every syntactically valid command using `--json` must be
+one parseable `sema.cli.result/v1` document containing exactly
+`schemaVersion`, `ok`, `kind`, `command`, `code`, `message`, `exitCode`, and
+`payload`. Smoke assertions must unwrap `payload` before checking
+command-specific fields, and recorded fixtures must contain that payload rather
+than either public CLI envelope. Coverage must include object, array, scalar,
+and `null` payloads, coherent `SUCCESS` and `DOMAIN_ERROR` results, process
+status equality, empty stderr, no `data` alias, and rejection of missing,
+extra, nested, or mismatched envelope fields. `--version` remains a plain exact
+SemVer text check.
+
+Focused distribution tests live in
+`testes/unidade/distribuicao-launcher-global.test.ts`,
+`testes/unidade/distribuicao-skill-global.test.ts`, and
+`testes/unidade/distribuicao-global.test.ts`. They must cover spaces, Unicode,
+argument forwarding, stale targets, ownership conflicts, symlink/junction
+escapes, atomic replacement, idempotent upgrades, the PowerShell fallback with
+an absolute system executable, a detected Claude mirror, and a local lifecycle
+no-op. No test may write to the real user home or a plugin cache.
+
+The public-package smoke has one orchestrator and named helpers under
+`scripts/cli-publico/`. All helpers share the same temporary sandbox and the
+same installed tarball; splitting the checks must never multiply installations
+or weaken the single `try/finally` cleanup boundary.
+
+Focused drift regressions live in
+`testes/unidade/drift-escopo-dependencias.test.ts`,
+`testes/unidade/drift-escopo-referencias.test.ts`,
+`testes/unidade/drift-catalogo.test.ts`,
+`testes/unidade/drift-leitura-compartilhada.test.ts`, and
+`testes/integracao/drift-escopo-io.test.ts`, plus the external-path attack
+regressions in `testes/integracao/drift-caminhos-externos.test.ts`. They must prove planning before
+cataloging, path confinement, dependency closure, one physical read and one AST
+per canonical file, no homonymous last-write-wins resolution, and no
+project-wide walk for `arquivo` or `modulo` scope. Project-loading regressions
+also prove deferred code discovery and rejection of external configured roots
+or contract origins before enumeration. In project scope, physical file
+bindings outside code roots must enter the safe catalog individually, including
+non-indexable assets, without causing a walk of their parent directories.
+Drift, impact, and semantic rename must not expose an external path or read its
+contents.
+Persistent-cache regressions live in
+`testes/unidade/drift-cache-modes.test.ts`,
+`testes/unidade/drift-cache-store.test.ts`,
+`testes/integracao/drift-cache-persistente.test.ts`, and
+`testes/integracao/drift-cli-modes.test.ts`. They must prove all three modes,
+query defaults, nullable non-evidence, zero cache I/O for `none`, storage outside
+the workspace, opaque paths, strong-content invalidation even with restored
+metadata, corruption recovery, immutable concurrent publication, and semantic
+equivalence between fresh and warm results. Shape-valid semantic tampering with
+only the envelope `payloadDigest` recalculated must fail the cross-index
+invariants, become a corrupt miss, recalculate, and match the fresh result. The
+payload must derive symbol, route, resource, and known-file aggregates from its
+canonical per-extractor indices instead of trusting redundant aggregate lists.
+A warm hit may skip AST/extractor work, but it never reuses the final score,
+links, diagnostics, or success decision. Junctions, symlinks, hardlinks, path
+traversal, drive-relative paths,
+intermediate-directory swaps, and cache unavailability must fail closed or
+degrade to an in-memory calculation without mutating the workspace.
+
+Cache digests are corruption checks, not authentication against a hostile
+process running as the same operating-system user. Tests must not present a
+warm cache hit as a protected trust boundary; final closure evidence uses
+`--cache fresh`.
 
 Native generator evidence is mandatory when changing C#/.NET or C++ support.
-The `dotnet` smoke must compile and execute through the local .NET SDK. The
-`cpp` smoke must compile and execute through GCC, Clang, or MSVC; checking only
-for generated files is not sufficient.
+The `dotnet` smoke must compile and execute through the local .NET SDK. The
+`cpp` smoke must compile and execute through GCC, Clang, or MSVC; checking only
+for generated files is not sufficient.

package/exemplos/express_crud.sema

@@ -0,0 +1,139 @@
+module exemplos.express.crud {
+  entity Monitor {
+    fields {
+      id: Id
+      nome: Texto
+      url: Texto
+      ativo: Booleano
+    }
+  }
+
+  task criar_monitor {
+    input {
+      nome: Texto required
+      url: Texto required
+    }
+    output {
+      monitor: Monitor
+    }
+    rules {
+      nome deve_ser preenchido
+      url deve_ser preenchido
+    }
+    effects {
+      persistencia Monitor
+      auditoria monitor_criado
+    }
+    guarantees {
+      monitor existe
+    }
+    tests {
+      caso "cria monitor" {
+        given {
+          nome: "API Pagamentos"
+          url: "https://api.exemplo.dev/status"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task listar_monitores {
+    input {
+      ativo: Booleano
+    }
+    output {
+      monitores: Lista
+    }
+    effects {
+      consulta Monitor
+    }
+    guarantees {
+      monitores existe
+    }
+    tests {
+      caso "lista monitores" {
+        given {
+          ativo: verdadeiro
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task remover_monitor {
+    input {
+      id: Id required
+    }
+    output {
+      removido: Booleano
+    }
+    rules {
+      id deve_ser valido
+    }
+    effects {
+      persistencia Monitor
+      auditoria monitor_removido
+    }
+    guarantees {
+      removido == verdadeiro
+    }
+    tests {
+      caso "remove monitor por id" {
+        given {
+          id: "mon_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  route monitores_criar {
+    metodo: POST
+    caminho: /monitores
+    task: criar_monitor
+    finalidade: cadastro_monitor
+    input {
+      nome: Texto
+      url: Texto
+    }
+    output {
+      monitor: Monitor
+    }
+  }
+
+  route monitores_listar {
+    metodo: GET
+    caminho: /monitores
+    task: listar_monitores
+    finalidade: consulta_monitores
+    input {
+      ativo: Booleano
+    }
+    output {
+      monitores: Lista
+    }
+  }
+
+  route monitores_remover {
+    metodo: DELETE
+    caminho: "/monitores/{id}"
+    task: remover_monitor
+    finalidade: exclusao_monitor
+    input {
+      id: Id
+    }
+    output {
+      removido: Booleano
+    }
+  }
+}

package/exemplos/fastify_crud.sema

@@ -0,0 +1,146 @@
+module exemplos.fastify.crud {
+  entity Pedido {
+    fields {
+      id: Id
+      cliente: Texto
+      total: Decimal
+      status: Texto
+    }
+  }
+
+  task criar_pedido {
+    input {
+      cliente: Texto required
+      total: Decimal required
+    }
+    output {
+      pedido: Pedido
+    }
+    rules {
+      cliente deve_ser preenchido
+      total deve_ser positivo
+    }
+    effects {
+      persistencia Pedido
+      auditoria pedido_criado
+    }
+    guarantees {
+      pedido existe
+    }
+    tests {
+      caso "cria pedido" {
+        given {
+          cliente: "Ana"
+          total: 149.9
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task obter_pedido {
+    input {
+      id: Id required
+    }
+    output {
+      pedido: Pedido
+    }
+    rules {
+      id deve_ser valido
+    }
+    effects {
+      consulta Pedido
+    }
+    guarantees {
+      pedido existe
+    }
+    tests {
+      caso "obtem pedido por id" {
+        given {
+          id: "ped_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task atualizar_pedido {
+    input {
+      id: Id required
+      status: Texto required
+    }
+    output {
+      pedido: Pedido
+    }
+    rules {
+      id deve_ser valido
+      status deve_ser preenchido
+    }
+    effects {
+      persistencia Pedido
+      auditoria pedido_atualizado
+    }
+    guarantees {
+      pedido existe
+    }
+    tests {
+      caso "atualiza status do pedido" {
+        given {
+          id: "ped_1"
+          status: "pago"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  route pedidos_criar {
+    metodo: POST
+    caminho: /pedidos
+    task: criar_pedido
+    finalidade: cadastro_pedido
+    input {
+      cliente: Texto
+      total: Decimal
+    }
+    output {
+      pedido: Pedido
+    }
+  }
+
+  route pedidos_obter {
+    metodo: GET
+    caminho: "/pedidos/{id}"
+    task: obter_pedido
+    finalidade: consulta_pedido
+    input {
+      id: Id
+    }
+    output {
+      pedido: Pedido
+    }
+  }
+
+  route pedidos_atualizar {
+    metodo: PATCH
+    caminho: "/pedidos/{id}"
+    task: atualizar_pedido
+    finalidade: alteracao_pedido
+    input {
+      id: Id
+      status: Texto
+    }
+    output {
+      pedido: Pedido
+    }
+  }
+}

package/exemplos/pipeline-conteudo/README.md

@@ -1,44 +1,44 @@
-# Content pipeline example
-
-This fixture proves that the pipeline core is independent from a platform,
-brand, or media type. One definition creates a global editorial core and two
-isolated target branches: a long-form document and a spoken audio episode.
-The same AI-native plan can add any number of channels and formats without
-making this experience the only delivery path.
-
-Definition v1 declares exactly one output per stage. Each stage also selects an
-  `adapterPolicy`: `NONE`, `CONSTRAINTS`, or `CONFIRMATION`. Constraint gates are
-  satisfied only by independently signed observations bound to the produced
-  artifact, including an independently observed media type; producer metadata
-  is not evidence of its own correctness.
-
-```bash
-sema conteudo validar exemplos/pipeline-conteudo/definicao.json --json
-sema conteudo planejar exemplos/pipeline-conteudo/definicao.json --alvos-arquivo exemplos/pipeline-conteudo/alvos.json --json
-```
-
-The example intentionally contains no private keys, signed policy, trust pins,
-ledger checkpoint, or signed events. In a live run, an authorized policy
-  authority must sign a policy bound to the execution and complete target set
-  through `runId` and `targetSetDigest`, with explicit `issuedAt` and `expiresAt`
-  authorization bounds. Every event must be recorded within that interval, and
-  every append also supplies that policy envelope. Keep the
-  trust-root digest, current `revocationDigest`, and
-required `expectedHead` outside the runner-controlled workspace. Generate
-events in independently controlled producer, evaluator, and adapter processes;
-  never commit production private keys to a Sema workspace. The adapter's
-  `requiredMetadata + optionalMetadata` is the exact scalar public allowlist;
-  artifact metadata is unavailable in v1. The runner resolves credentials
-  externally from a strict `account:<alias>` reference.
-
-Every gate declares separate deterministic-attester and semantic-AI quorums.
-Use `content.evidence.attest:<evidenceType>` for ordinary attestations. Adapter
-observations use the stricter
-`content.adapter.attest:<adapterId>@<version>:<evidenceType>` capability and
-signed adapter/version binding; a generic receipt capability is intentionally
-insufficient.
-
-The runner executes and resumes work from Sema's derived `nextActions`. It does
-not calculate verdicts or edit completion state. Operational conditions remain
-separate from gate verdicts, and every generated manifest is a non-authoritative
-projection of the canonical ledger. There is no native human-review fallback.
+# Content pipeline example
+
+This fixture proves that the pipeline core is independent from a platform,
+brand, or media type. One definition creates a global editorial core and two
+isolated target branches: a long-form document and a spoken audio episode.
+The same AI-native plan can add any number of channels and formats without
+making this experience the only delivery path.
+
+Definition v1 declares exactly one output per stage. Each stage also selects an
+  `adapterPolicy`: `NONE`, `CONSTRAINTS`, or `CONFIRMATION`. Constraint gates are
+  satisfied only by independently signed observations bound to the produced
+  artifact, including an independently observed media type; producer metadata
+  is not evidence of its own correctness.
+
+```bash
+sema conteudo validar exemplos/pipeline-conteudo/definicao.json --json
+sema conteudo planejar exemplos/pipeline-conteudo/definicao.json --alvos-arquivo exemplos/pipeline-conteudo/alvos.json --json
+```
+
+The example intentionally contains no private keys, signed policy, trust pins,
+ledger checkpoint, or signed events. In a live run, an authorized policy
+  authority must sign a policy bound to the execution and complete target set
+  through `runId` and `targetSetDigest`, with explicit `issuedAt` and `expiresAt`
+  authorization bounds. Every event must be recorded within that interval, and
+  every append also supplies that policy envelope. Keep the
+  trust-root digest, current `revocationDigest`, and
+required `expectedHead` outside the runner-controlled workspace. Generate
+events in independently controlled producer, evaluator, and adapter processes;
+  never commit production private keys to a Sema workspace. The adapter's
+  `requiredMetadata + optionalMetadata` is the exact scalar public allowlist;
+  artifact metadata is unavailable in v1. The runner resolves credentials
+  externally from a strict `account:<alias>` reference.
+
+Every gate declares separate deterministic-attester and semantic-AI quorums.
+Use `content.evidence.attest:<evidenceType>` for ordinary attestations. Adapter
+observations use the stricter
+`content.adapter.attest:<adapterId>@<version>:<evidenceType>` capability and
+signed adapter/version binding; a generic receipt capability is intentionally
+insufficient.
+
+The runner executes and resumes work from Sema's derived `nextActions`. It does
+not calculate verdicts or edit completion state. Operational conditions remain
+separate from gate verdicts, and every generated manifest is a non-authoritative
+projection of the canonical ledger. There is no native human-review fallback.

package/exemplos/pipeline-conteudo/alvos.json

@@ -1,23 +1,23 @@
-[
-  {
-    "targetId": "documento-principal",
-    "adapterId": "destination.document",
-    "accountScope": "account:publisher.site-a",
-    "formatProfileId": "long-form",
-    "locale": "pt-BR",
-    "metadata": {
-      "title": "Exemplo de conteúdo multiformato"
-    }
-  },
-  {
-    "targetId": "episodio-audio",
-    "adapterId": "destination.audio-feed",
-    "accountScope": "account:publisher.feed-a",
-    "formatProfileId": "spoken-episode",
-    "locale": "pt-BR",
-    "metadata": {
-      "title": "Exemplo de conteúdo multiformato",
-      "description": "A mesma intenção editorial em um destino de áudio independente."
-    }
-  }
-]
+[
+  {
+    "targetId": "documento-principal",
+    "adapterId": "destination.document",
+    "accountScope": "account:publisher.site-a",
+    "formatProfileId": "long-form",
+    "locale": "pt-BR",
+    "metadata": {
+      "title": "Exemplo de conteúdo multiformato"
+    }
+  },
+  {
+    "targetId": "episodio-audio",
+    "adapterId": "destination.audio-feed",
+    "accountScope": "account:publisher.feed-a",
+    "formatProfileId": "spoken-episode",
+    "locale": "pt-BR",
+    "metadata": {
+      "title": "Exemplo de conteúdo multiformato",
+      "description": "A mesma intenção editorial em um destino de áudio independente."
+    }
+  }
+]