@semacode/cli 2.3.0 → 3.0.0

package/docs/testing.md

@@ -2,7 +2,7 @@
 
 Public Sema tests should run locally.
 
-Recommended checks:
+Recommended checks:
 
 ```bash
 npm run build
@@ -11,15 +11,31 @@ 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
+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
-```
+npm run release:verificar-drift
+```
+
+`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
@@ -31,14 +47,104 @@ 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.
-
-Native generator evidence is mandatory when changing C#/.NET or C++ support.
+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. 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.

package/docs/vocabulary.md

@@ -1,29 +1,29 @@
-# Sema Vocabulary
-
-Use consistent English prose in public docs while preserving technical
-identifiers.
-
-## Canonical Concepts
-
-- semantic contract
-- drift
-- impact map
-- governed code
-- traceability
-- Codex-native
-- local runtime
-- finalization
-- evidence
-- local CLI
-
-## Do Not Translate
-
-- commands: `sema validar`, `sema drift`, `sema impacto`
-- files: `AGENTS.md`, `SEMA_BOOT.md`, `SEMA_INDEX.json`
-- DSL keywords: `task`, `input`, `output`, `rules`, `effects`, `guarantees`
-- package names: `@semacode/cli`
-- code symbols and environment variable names
-
-## Public Support
-
-Use suporte@otimitare.online for support references.
+# Sema Vocabulary
+
+Use consistent English prose in public docs while preserving technical
+identifiers.
+
+## Canonical Concepts
+
+- semantic contract
+- drift
+- impact map
+- governed code
+- traceability
+- Codex-native
+- local runtime
+- finalization
+- evidence
+- local CLI
+
+## Do Not Translate
+
+- commands: `sema validar`, `sema drift`, `sema impacto`
+- files: `AGENTS.md`, `SEMA_BOOT.md`, `SEMA_INDEX.json`
+- DSL keywords: `task`, `input`, `output`, `rules`, `effects`, `guarantees`
+- package names: `@semacode/cli`
+- code symbols and environment variable names
+
+## Public Support
+
+Use suporte@otimitare.online for support references.

package/exemplos/agendamento.sema

@@ -102,4 +102,4 @@ module exemplos.agendamento {
       }
     }
   }
-}
+}

package/exemplos/assinatura.sema

@@ -130,4 +130,4 @@ module exemplos.assinatura {
       }
     }
   }
-}
+}

package/exemplos/auditoria.sema

@@ -86,4 +86,4 @@ module exemplos.auditoria {
       }
     }
   }
-}
+}

package/exemplos/autenticacao.sema

@@ -122,4 +122,4 @@ module exemplos.autenticacao {
       }
     }
   }
-}
+}

package/exemplos/author_obra_comum.sema

@@ -291,4 +291,4 @@ module exemplos.author.obra_comum {
       auditoria author_flow criticidade = media
     }
   }
-}
+}

package/exemplos/author_tema_sensivel.sema

@@ -261,4 +261,4 @@ module exemplos.author.tema_sensivel {
       auditoria author_flow_sensivel criticidade = alta
     }
   }
-}
+}

package/exemplos/automacao.sema

@@ -104,4 +104,4 @@ module exemplos.automacao {
     etapa auditar usa registrar_auditoria com protocolo = receber.protocolo depende_de receber
     etapa registrar_falha usa registrar_falha_onboarding com lead_id = lead_id depende_de receber
   }
-}
+}

package/exemplos/cadastro_usuario.sema

@@ -51,4 +51,4 @@ module exemplos.cadastro.usuario {
       }
     }
   }
-}
+}

package/exemplos/calculadora.sema

@@ -75,4 +75,4 @@ module exemplos.calculadora {
       }
     }
   }
-}
+}

package/exemplos/crud_simples.sema

@@ -86,4 +86,4 @@ module exemplos.crud.simples {
       produto: Produto
     }
   }
-}
+}

package/exemplos/estoque.sema

@@ -124,4 +124,4 @@ module exemplos.estoque {
       }
     }
   }
-}
+}

package/exemplos/exportacao.sema

@@ -91,4 +91,4 @@ module exemplos.exportacao {
       }
     }
   }
-}
+}

package/exemplos/fila.sema

@@ -127,4 +127,4 @@ module exemplos.fila {
       }
     }
   }
-}
+}

package/exemplos/integracao_externa.sema

@@ -91,4 +91,4 @@ module exemplos.integracao.externa {
       }
     }
   }
-}
+}

package/exemplos/multi_tenant.sema

@@ -137,4 +137,4 @@ module exemplos.multi.tenant {
       }
     }
   }
-}
+}

package/exemplos/notificacao.sema

@@ -146,4 +146,4 @@ module exemplos.notificacao {
     etapa registrar_falha_push usa registrar_falha_notificacao com canal = canal_push depende_de push
     etapa concluir usa confirmar_notificacao com destinatario_id = destinatario_id depende_de email
   }
-}
+}

package/exemplos/operacao_estrategia.sema

@@ -1,132 +1,132 @@
-module exemplos.operacao_estrategia {
-  docs {
-    resumo: "Referencia oficial de governanca operacional para strategy,slice,gate,discovery semanal e rollout. Este indice fino mantem modelos compartilhados e flow; as tasks ficam em arquivos filhos por responsabilidade."
-  }
-
-  type JanelaDiscovery {
-    fields {
-      semana_referencia: Data
-      strategy_id: Id
-      versao_modelo_candidata: Texto
-      status_discovery: StatusDiscovery
-    }
-    invariants {
-      semana_referencia existe
-      strategy_id existe
-      versao_modelo_candidata existe
-      status_discovery em [ABERTA, EM_AVALIACAO, APROVADA, REJEITADA]
-    }
-  }
-
-  type ContextoQuarentena {
-    fields {
-      motivo: Texto
-      origem: Texto
-      desde: Data
-    }
-    invariants {
-      motivo existe
-      origem existe
-      desde existe
-    }
-  }
-
-  entity Strategy {
-    fields {
-      id: Id
-      versao_modelo_ativa: Texto
-      versao_modelo_candidata: Texto
-      status: StatusStrategy
-      gate_global: StatusGate
-      discovery_atual: JanelaDiscovery
-      ultima_quarentena: ContextoQuarentena
-    }
-    invariants {
-      id existe
-      versao_modelo_ativa existe
-      versao_modelo_candidata existe
-      status em [RASCUNHO, ATIVA, QUARENTENA, DESATIVADA]
-      gate_global em [ABERTO, FECHADO]
-      discovery_atual existe
-      ultima_quarentena existe
-    }
-  }
-
-  entity Slice {
-    fields {
-      id: Id
-      strategy_id: Id
-      status: StatusSlice
-      gate: StatusGate
-      versao_modelo_ativa: Texto
-      versao_modelo_candidata: Texto
-      motivo_quarentena: Texto
-      precision_observada: Decimal
-    }
-    invariants {
-      id existe
-      strategy_id existe
-      status em [ATIVO, QUARENTENA, DESLIGADO]
-      gate em [ABERTO, FECHADO]
-      versao_modelo_ativa existe
-      versao_modelo_candidata existe
-      motivo_quarentena existe
-      precision_observada existe
-    }
-  }
-
-  enum StatusStrategy {
-    RASCUNHO,
-    ATIVA,
-    QUARENTENA,
-    DESATIVADA
-  }
-
-  enum StatusSlice {
-    ATIVO,
-    QUARENTENA,
-    DESLIGADO
-  }
-
-  enum StatusGate {
-    ABERTO,
-    FECHADO
-  }
-
-  enum StatusDiscovery {
-    ABERTA,
-    EM_AVALIACAO,
-    APROVADA,
-    REJEITADA
-  }
-
-  state governanca_estrategia {
-    fields {
-      status: StatusStrategy
-      slice_status: StatusSlice
-      gate_global: StatusGate
-      gate_slice: StatusGate
-      discovery_status: StatusDiscovery
-      versao_modelo_ativa: Texto
-      versao_modelo_candidata: Texto
-      motivo_operacional: Texto
-    }
-    invariants {
-      status em [RASCUNHO, ATIVA, QUARENTENA, DESATIVADA]
-      slice_status em [ATIVO, QUARENTENA, DESLIGADO]
-      gate_global em [ABERTO, FECHADO]
-      gate_slice em [ABERTO, FECHADO]
-      discovery_status em [ABERTA, EM_AVALIACAO, APROVADA, REJEITADA]
-      versao_modelo_ativa existe
-      versao_modelo_candidata existe
-      motivo_operacional existe
-    }
-    transitions {
-      RASCUNHO -> ATIVA
-      ATIVA -> QUARENTENA
-      QUARENTENA -> ATIVA
-      ATIVA -> DESATIVADA
-    }
-  }
-
-}
+module exemplos.operacao_estrategia {
+  docs {
+    resumo: "Referencia oficial de governanca operacional para strategy,slice,gate,discovery semanal e rollout. Este indice fino mantem modelos compartilhados e flow; as tasks ficam em arquivos filhos por responsabilidade."
+  }
+
+  type JanelaDiscovery {
+    fields {
+      semana_referencia: Data
+      strategy_id: Id
+      versao_modelo_candidata: Texto
+      status_discovery: StatusDiscovery
+    }
+    invariants {
+      semana_referencia existe
+      strategy_id existe
+      versao_modelo_candidata existe
+      status_discovery em [ABERTA, EM_AVALIACAO, APROVADA, REJEITADA]
+    }
+  }
+
+  type ContextoQuarentena {
+    fields {
+      motivo: Texto
+      origem: Texto
+      desde: Data
+    }
+    invariants {
+      motivo existe
+      origem existe
+      desde existe
+    }
+  }
+
+  entity Strategy {
+    fields {
+      id: Id
+      versao_modelo_ativa: Texto
+      versao_modelo_candidata: Texto
+      status: StatusStrategy
+      gate_global: StatusGate
+      discovery_atual: JanelaDiscovery
+      ultima_quarentena: ContextoQuarentena
+    }
+    invariants {
+      id existe
+      versao_modelo_ativa existe
+      versao_modelo_candidata existe
+      status em [RASCUNHO, ATIVA, QUARENTENA, DESATIVADA]
+      gate_global em [ABERTO, FECHADO]
+      discovery_atual existe
+      ultima_quarentena existe
+    }
+  }
+
+  entity Slice {
+    fields {
+      id: Id
+      strategy_id: Id
+      status: StatusSlice
+      gate: StatusGate
+      versao_modelo_ativa: Texto
+      versao_modelo_candidata: Texto
+      motivo_quarentena: Texto
+      precision_observada: Decimal
+    }
+    invariants {
+      id existe
+      strategy_id existe
+      status em [ATIVO, QUARENTENA, DESLIGADO]
+      gate em [ABERTO, FECHADO]
+      versao_modelo_ativa existe
+      versao_modelo_candidata existe
+      motivo_quarentena existe
+      precision_observada existe
+    }
+  }
+
+  enum StatusStrategy {
+    RASCUNHO,
+    ATIVA,
+    QUARENTENA,
+    DESATIVADA
+  }
+
+  enum StatusSlice {
+    ATIVO,
+    QUARENTENA,
+    DESLIGADO
+  }
+
+  enum StatusGate {
+    ABERTO,
+    FECHADO
+  }
+
+  enum StatusDiscovery {
+    ABERTA,
+    EM_AVALIACAO,
+    APROVADA,
+    REJEITADA
+  }
+
+  state governanca_estrategia {
+    fields {
+      status: StatusStrategy
+      slice_status: StatusSlice
+      gate_global: StatusGate
+      gate_slice: StatusGate
+      discovery_status: StatusDiscovery
+      versao_modelo_ativa: Texto
+      versao_modelo_candidata: Texto
+      motivo_operacional: Texto
+    }
+    invariants {
+      status em [RASCUNHO, ATIVA, QUARENTENA, DESATIVADA]
+      slice_status em [ATIVO, QUARENTENA, DESLIGADO]
+      gate_global em [ABERTO, FECHADO]
+      gate_slice em [ABERTO, FECHADO]
+      discovery_status em [ABERTA, EM_AVALIACAO, APROVADA, REJEITADA]
+      versao_modelo_ativa existe
+      versao_modelo_candidata existe
+      motivo_operacional existe
+    }
+    transitions {
+      RASCUNHO -> ATIVA
+      ATIVA -> QUARENTENA
+      QUARENTENA -> ATIVA
+      ATIVA -> DESATIVADA
+    }
+  }
+
+}