@semacode/cli 2.3.0 → 3.0.0

package/dist/skillCommand.d.ts

@@ -0,0 +1,5 @@
+import { type ResultadoDistribuicaoGlobal } from "./distribuicao/index.js";
+type OperacaoSkill = "status" | "sync";
+export declare function renderizarResultadoSkill(operacao: OperacaoSkill, resultado: ResultadoDistribuicaoGlobal): string;
+export declare function comandoSkill(posicionais: string[], args: string[], emJson: boolean): Promise<number>;
+export {};

package/dist/skillCommand.js

@@ -0,0 +1,88 @@
+// SEMA-GOVERNED: sema.produto.distribuicao_global, sema.produto.distribuicao_global.skill
+// Descrição: expõe diagnóstico read-only e reparo explícito da distribuição global gerenciada.
+import { sincronizarDistribuicaoGlobal, statusDistribuicaoGlobal, } from "./distribuicao/index.js";
+export function renderizarResultadoSkill(operacao, resultado) {
+    const linhas = [
+        `Distribuição global Sema (${operacao}): ${resultado.estado}`,
+        `  Alterada: ${resultado.alterado ? "sim" : "não"}`,
+        `  Launcher: ${resultado.launcher.estado} (${resultado.launcher.destino_simbolico})`,
+        ...(resultado.launcher.fallback_simbolico
+            ? [`  Fallback PowerShell: ${resultado.launcher.fallback_simbolico}`]
+            : []),
+        `  Diagnóstico launcher: ${resultado.launcher.codigo}`,
+        `  Skill: ${resultado.skill.estado} (${resultado.skill.origem_simbolica})`,
+        `  Destino .agents: ${resultado.skill.destino_agents}`,
+        `  Destino Claude: ${resultado.skill.destino_claude}`,
+        `  Diagnósticos skill: ${resultado.skill.destinos
+            .map((destino) => `${destino.id}=${destino.codigo}`)
+            .join(", ") || "nenhum"}`,
+    ];
+    return linhas.join("\n");
+}
+function imprimirSubcomandoInvalido(emJson) {
+    const mensagem = "Use `sema skill status` ou `sema skill sync`.";
+    if (emJson) {
+        console.log(JSON.stringify({
+            schema: "sema.skill-distribution/v1",
+            comando: "skill",
+            sucesso: false,
+            erro: {
+                codigo: "SUBCOMANDO_SKILL_INVALIDO",
+                mensagem,
+            },
+        }, null, 2));
+        return;
+    }
+    console.error(mensagem);
+}
+export async function comandoSkill(posicionais, args, emJson) {
+    const operacao = (posicionais[0] ?? "status").toLocaleLowerCase("en-US");
+    const possuiArgumentoExtra = posicionais.length > 1;
+    const possuiFlagDesconhecida = args.some((arg) => arg.startsWith("-") && arg !== "--json");
+    if ((operacao !== "status" && operacao !== "sync")
+        || possuiArgumentoExtra
+        || possuiFlagDesconhecida) {
+        imprimirSubcomandoInvalido(emJson);
+        return 1;
+    }
+    try {
+        const resultado = operacao === "sync"
+            ? await sincronizarDistribuicaoGlobal()
+            : await statusDistribuicaoGlobal();
+        const sucesso = resultado.estado === "READY";
+        if (emJson) {
+            const payload = {
+                schema: "sema.skill-distribution/v1",
+                comando: "skill",
+                operacao,
+                sucesso,
+                resultado,
+            };
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(renderizarResultadoSkill(operacao, resultado));
+        }
+        return sucesso ? 0 : 1;
+    }
+    catch {
+        const mensagem = "Falha ao consultar ou sincronizar a distribuição global Sema.";
+        if (emJson) {
+            console.log(JSON.stringify({
+                schema: "sema.skill-distribution/v1",
+                comando: "skill",
+                operacao,
+                sucesso: false,
+                erro: {
+                    codigo: "FALHA_DISTRIBUICAO_GLOBAL",
+                    mensagem,
+                },
+            }, null, 2));
+        }
+        else {
+            console.error(mensagem);
+        }
+        return 1;
+    }
+}
+//# sourceMappingURL=skillCommand.js.map

package/dist/sync/index.js

@@ -46,25 +46,25 @@ export async function gerarSchemaPrisma(pastaContratos, saidaSchema, datasourceP
     for (const contrato of contratos) {
         const nomeModel = path.basename(contrato, '.sema').replace(/\./g, '_');
         // Schema simplificado - em producao, fazer parsing real do contrato
-        models += `\nmodel ${nomeModel.charAt(0).toUpperCase() + nomeModel.slice(1)} {
-  id        String   @id @default(uuid())
-  criadoEm  DateTime @default(now())
-  // Gerado a partir de: ${contrato}
-  // TODO: Adicionar campos do contrato Sema
+        models += `\nmodel ${nomeModel.charAt(0).toUpperCase() + nomeModel.slice(1)} {
+  id        String   @id @default(uuid())
+  criadoEm  DateTime @default(now())
+  // Gerado a partir de: ${contrato}
+  // TODO: Adicionar campos do contrato Sema
 }\n`;
         modelCount++;
     }
-    const schema = `// Gerado automaticamente pelo Sema
-// Fonte: ${pastaContratos}
-
-generator client {
-  provider = "prisma-client-js"
-}
-
-datasource db {
-  provider = "${datasourceProvider}"
-  url      = env("SEMA_PRISMA_URL")
-}
+    const schema = `// Gerado automaticamente pelo Sema
+// Fonte: ${pastaContratos}
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "${datasourceProvider}"
+  url      = env("SEMA_PRISMA_URL")
+}
 ${models}`;
     // Salvar
     fs.writeFileSync(saidaSchema, schema, 'utf-8');
@@ -90,25 +90,25 @@ export async function importarSchemaPrisma(caminhoSchema, pastaSaida, nomeModulo
         const nomeContrato = `${nomeModel.toLowerCase()}.sema`;
         const caminhoContrato = path.join(pastaSaida, nomeContrato);
         // Gerar contrato basico
-        const conteudo = `module ${nomeModulo}.${nomeModel.toLowerCase()} {
-  entity ${nomeModel} {
-    fields {
-      id: Id
-      // TODO: Mapear campos do schema Prisma
-    }
-  }
-
-  task criar_${nomeModel.toLowerCase()} {
-    input {
-      // TODO: Definir inputs
-    }
-    output {
-      ${nomeModel.toLowerCase()}: ${nomeModel}
-    }
-    effects {
-      persistencia ${nomeModel}
-    }
-  }
+        const conteudo = `module ${nomeModulo}.${nomeModel.toLowerCase()} {
+  entity ${nomeModel} {
+    fields {
+      id: Id
+      // TODO: Mapear campos do schema Prisma
+    }
+  }
+
+  task criar_${nomeModel.toLowerCase()} {
+    input {
+      // TODO: Definir inputs
+    }
+    output {
+      ${nomeModel.toLowerCase()}: ${nomeModel}
+    }
+    effects {
+      persistencia ${nomeModel}
+    }
+  }
 }`;
         fs.writeFileSync(caminhoContrato, conteudo, 'utf-8');
         contratos.push(caminhoContrato);

package/docs/README.md

@@ -2,10 +2,13 @@
 
 These docs describe the public Codex-native local CLI distribution of Sema.
 
-Sema is local-first: Codex runs the CLI inside a project folder, reads `.sema`
-contracts, checks drift, maps impact, and closes changes with documentation
-evidence. `AGENTS.md` is the official Codex entrypoint. Public docs are written
-in English.
+Sema is local-first: Codex runs the CLI inside a project folder, reads `.sema`
+contracts, checks drift, maps impact, and closes changes with documentation
+evidence. In 3.0.0, valid commands using `--json` return the exact
+`sema.cli.result/v1` envelope with command data nested under `payload`, while
+help and command-control failures keep the separate `sema.cli.control/v1`
+envelope. `AGENTS.md` is the official Codex entrypoint. Public docs are written
+in English.
 
 Sema is an independent product and is not affiliated with or endorsed by
 OpenAI. Codex-native describes Sema's product direction, not an official OpenAI
@@ -13,9 +16,10 @@ program or submission.
 
 Start here:
 
-- [CLI](./cli.md)
-- [Commands](./commands.md)
-- [Syntax](./syntax.md)
+- [CLI](./cli.md) — installation and the public JSON output contract
+- [Commands](./commands.md) — command catalog and envelope-consumption rules
+- [Drift Cache And Query Evidence](./drift-cache.md)
+- [Syntax](./syntax.md)
 - [Profiles](./profiles.md)
 - [Capability Discovery](./descoberta-capacidades.md) — one explainable catalog
   for governance flows, profiles, specialized workflows, pipelines, generators,

package/docs/ai-integration.md

@@ -11,18 +11,22 @@ https://learn.chatgpt.com/docs/agent-configuration/agents-md.
 
 ## Before AGENTS.md Exists
 
-The official Sema skill is the required first-contact bootstrap for Codex in a
-project that does not have Sema yet. Install it explicitly:
+The official Sema skill is the first-contact bootstrap for a project that does
+not have Sema yet. A global CLI install bundles and synchronizes it:
 
 ```bash
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
+npm install -g @semacode/cli
+sema skill status --json
 ```
 
-The skill locates the local CLI, runs `sema iniciar`, generates `AGENTS.md`, and
-then delegates all ongoing workspace governance to that file. It contains no
+The package creates an absolute launcher under `~/.sema/bin`, synchronizes the
+canonical skill under `~/.agents/skills/sema`, and mirrors Claude only when
+detected. Informational requests stay read-only; before implementation the skill asks
+for explicit project-adoption authorization, then generates `AGENTS.md` and delegates
+ongoing governance. Installing or updating the global CLI authorizes distribution only.
+Already-open tasks may need a reload. The distribution contains no
 MCP server, remote workspace bridge, login, license, billing, token, credit,
-panel, or authorization gate.
+panel, or runtime authorization gate.
 
 Supported capacity labels: fraca, pequena, media, forte, grande.
 
@@ -32,10 +36,11 @@ For a local workspace, use the local CLI:
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 ```
 
-A successful `sema --version` is enough to use the local CLI directly. Local
+If the shell cannot resolve `sema`, use `~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell uses `sema.ps1` from PATH and cmd.exe uses `sema.cmd`; use `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version` as the absolute fallback
+before declaring the CLI unavailable. A successful version check is enough. Local
 commands require no login, activation key, license check, token, credits, billing
 service, control panel, or external authorization request.
 
@@ -43,13 +48,15 @@ service, control panel, or external authorization request.
 
 ```bash
 sema docs-impacto --intencao "describe the change" --json
-sema inspecionar contratos/example.sema --json
-sema drift contratos/example.sema --escopo modulo --json
+sema inspecionar contratos/example.sema --drift none --json
+sema drift contratos/example.sema --escopo modulo --cache fresh --json
 sema impacto contratos/example.sema --alvo app.example --mudanca "describe the change" --json
 ```
 
 Read every document listed by `docs-impacto` before changing code, contracts,
 operational docs, generated artifacts, workflows, profiles, or release material.
+A cache hit is acceleration, not evidence: closing requires `--cache fresh`,
+while contract-only queries keep unobserved implementation fields null inside the command payload.
 
 ## Codex Context Tiers
 

package/docs/ai-onboarding.md

@@ -1,62 +1,81 @@
-# Codex Onboarding
-
-The official Sema skill is required for Codex to recognize and initialize Sema
-before a project has its own protocol:
-
-```bash
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
-```
-
-Open a new Codex task in the target repository after installation. Codex loads
-the plugin/skill catalog at task start, so `$sema` is not added retroactively to
-an already-open task. Invoke `$sema` in the new task; it bootstraps the project,
-reads the generated `AGENTS.md`, and later tasks load that protocol
-automatically.
-
-`AGENTS.md` is the official Sema entrypoint for Codex. It gives Codex the durable
-repository rule that contracts come first and the local CLI is the source of
-truth. Once the file exists, the skill delegates to it instead of carrying a
-second copy of the governed workflow.
-
-Create or refresh the entrypoint with:
-
-```bash
-sema sync-codex --json
-```
-
-## Minimal Prompt
-
-```text
-This workspace is governed by Sema. Before editing code, contracts, docs,
-workflows, profiles, or release scripts, run:
-
-1. sema --version
-2. sema resumo
-3. sema docs-impacto --intencao "<change>" --json
-4. sema inspecionar on the applicable .sema contract
-5. sema drift before editing existing code
-6. sema impacto before changing behavior
-7. sema finalizar-mudanca before closing
-
-If the CLI is unavailable, stop and install or repair @semacode/cli. There is
-no separate Sema login, license activation, or authorization gate. Do not
-replace Sema with manual search or guessed contracts.
-```
-
-## What Codex Should Not Do
-
-- Do not invent `.sema` contracts.
-- Do not implement code without an applicable contract.
-- Do not ignore severity 4+ warnings.
-- Do not publish private or sensitive operational material.
-- Do not replace the local CLI when the local workspace is available.
-
-Other AI clients can invoke the public CLI manually, but Sema does not ship or
-manage an official repository entrypoint for them. The supported product path
-is Codex plus `AGENTS.md`.
-
-Sema is an independent product and is not affiliated with or endorsed by
-OpenAI.
-
-Support: suporte@otimitare.online
+# Codex Onboarding
+
+The official Sema skill lets Codex and compatible agents recognize and
+initialize Sema before a project has its own protocol:
+
+```bash
+npm install -g @semacode/cli
+sema skill status --json
+```
+
+The install maintains the canonical copy in `~/.agents/skills/sema` and a Claude
+mirror in `~/.claude/skills/sema` only when Claude is detected. Open a new task
+after installation or update because an already-open task does not reload its
+skill catalog. Invoking `$sema` for information does not initialize the
+workspace. Before implementation, the skill asks for explicit adoption
+authorization; installing or updating the global CLI authorizes distribution
+changes only. After authorized adoption, it reads the generated `AGENTS.md`,
+and later tasks load that protocol automatically.
+
+The optional Codex plugin remains available as a separate namespaced channel;
+the npm lifecycle never writes into its cache.
+
+`AGENTS.md` is the official Sema entrypoint for Codex. It gives Codex the durable
+repository rule that contracts come first and the local CLI is the source of
+truth. Once the file exists, the skill delegates to it instead of carrying a
+second copy of the governed workflow.
+
+Create or refresh the entrypoint with:
+
+```bash
+sema sync-codex --json
+```
+
+## Minimal Prompt
+
+```text
+This workspace is governed by Sema. Before editing code, contracts, docs,
+workflows, profiles, or release scripts, run:
+
+1. sema --version
+2. sema resumo --drift none
+3. sema docs-impacto --intencao "<change>" --json
+4. sema inspecionar <contract.sema> --drift none --json
+5. sema drift <contract.sema> --escopo modulo --cache fresh --json before
+   editing existing code
+6. sema impacto before changing behavior
+7. sema finalizar-mudanca before closing
+
+If `sema --version` is unavailable, try the managed absolute launcher at
+`~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell uses `sema.ps1` from
+`PATH`, `cmd.exe` uses `sema.cmd`, and the absolute PowerShell fallback is:
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+If that also fails, stop and install or repair @semacode/cli. There is no
+separate Sema login or license-activation gate. Distribution installation does
+not authorize workspace adoption. Do not replace Sema with manual search or
+guessed contracts.
+```
+
+Query commands default to `--drift none`, so their `analiseDrift` envelope marks
+the analysis as not executed and keeps drift-derived evidence `null`. Direct
+`sema drift` defaults to `--cache fresh`; `--cache none` still executes drift
+without persistent cache access. The cache is non-authoritative, lives outside
+the workspace, and safely falls back to recalculation when unavailable or
+corrupt. See [Drift Cache And Query Evidence](./drift-cache.md).
+
+## What Codex Should Not Do
+
+- Do not invent `.sema` contracts.
+- Do not implement code without an applicable contract.
+- Do not ignore severity 4+ warnings.
+- Do not publish private or sensitive operational material.
+- Do not replace the local CLI when the local workspace is available.
+
+Compatible AI clients can discover the same portable skill through the
+canonical global `.agents/skills` root. Sema does not create client-specific
+repository rules: `AGENTS.md` remains the only official workspace entrypoint.
+
+Sema is an independent product and is not affiliated with or endorsed by
+OpenAI.
+
+Support: suporte@otimitare.online

package/docs/ai-workflow.md

@@ -4,20 +4,26 @@
 This is the minimum workflow for Codex in a local workspace.
 
 1. Read `SEMA_BOOT.md`.
-2. Run `sema --version`. Success enables direct local execution; there is no login, license, token, billing, panel, or authorization gate.
-3. Run `sema resumo`.
+2. Run `sema --version`. If the shell cannot find it, use `$HOME/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell resolves `sema.ps1` from PATH and cmd.exe resolves `sema.cmd`; use `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version` as the absolute fallback. Only then declare the CLI unavailable.
+3. Run `sema resumo --drift none` for contract-only orientation; request `--drift cache` or `--drift fresh` only when code evidence is needed.
 4. Run `sema docs-impacto --intencao "<change>" --json`.
 5. Read every required document returned by the command.
 6. Read `docs/commands.md` before selecting a command or interpreting `--saida`.
 7. If the right capability is unclear, run `sema descobrir recomendar --intencao "<goal>" --json`; do not auto-run ambiguous recommendations.
 8. Use `exemplos/` and `docs/syntax.md` before creating or editing a contract.
-9. Run `sema drift` and `sema impacto` before editing existing code.
+9. Run `sema drift --cache fresh` and `sema impacto` before editing existing code.
 10. Run `sema formatar` and `sema validar` after changing a `.sema` contract.
 11. Run `sema finalizar-mudanca` with the documents read before closure.
 
 Contract edit rule: `.sema` has its own size budget. Above 300 lines, plan a split by domain/capability; above 500, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through `vinculos`.
 
-Closing rule: `sema drift --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or broken impls, the task is still blocked. Passing unit tests do not replace green drift.
+Closing rule: the `payload` of `sema drift --cache fresh --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. In 3.0.0, `ok` describes the CLI result path and never replaces a command-specific domain verdict.
+
+Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit `--escopo projeto`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. `inspecionar`, `impacto`, and `renomear-semantico` preserve the same directed boundary. Missing local dependencies make coverage partial and block success.
+
+Cache rule: a closure gate should use `sema drift <contrato> --escopo modulo --cache fresh --json`. `--cache none` executes the same analysis without persistent-cache I/O, while `--cache cache` may reuse only extraction data whose schema, workspace identity, Git HEAD, plan, configuration, contracts, member paths, and strong content digests all match. Cache objects are stored in the operating system's user-cache directory, never below the workspace. A hit is acceleration, not evidence: final links, diagnostics, score, and success are always recalculated. Corruption or an unavailable cache degrades to an in-memory calculation.
+
+Query honesty rule: `resumo` and `inspecionar` default to `--drift none`. When analysis is skipped, score, confidence, implementation, routes, and other unobserved code claims inside the command payload must be `null` or explicitly marked not evaluated; zero is not a substitute for absent evidence.
 
 UI rule: if the task involves an interface, minimum evidence includes desktop and mobile. On a narrow viewport such as 390px, `document.documentElement.scrollWidth <= document.documentElement.clientWidth` must pass; horizontal scroll blocks closure.
 

package/docs/auth.md

@@ -1,26 +1,26 @@
-# Local Runtime Boundary
-
-The public Sema CLI executes directly against the local workspace. It does not
-require a Sema login, user authentication, product authorization, license
-activation, install key, token, credits, billing service, control panel, or an
-external request.
-
-Use local commands:
-
-```bash
-sema --version
-sema resumo
-sema validar contratos/example.sema --json
-```
-
-The repository license governs use and redistribution. It is not checked as a
-runtime activation mechanism.
-
-An `authz` block inside a `.sema` contract describes authorization in the
-application being governed. It does not authenticate a person before the Sema
-CLI can run.
-
-Do not put private or sensitive operational material in this repository.
-
-Application-specific authentication belongs in the application repository that
-owns it.
+# Local Runtime Boundary
+
+The public Sema CLI executes directly against the local workspace. It does not
+require a Sema login, user authentication, product authorization, license
+activation, install key, token, credits, billing service, control panel, or an
+external request.
+
+Use local commands:
+
+```bash
+sema --version
+sema resumo
+sema validar contratos/example.sema --json
+```
+
+The repository license governs use and redistribution. It is not checked as a
+runtime activation mechanism.
+
+An `authz` block inside a `.sema` contract describes authorization in the
+application being governed. It does not authenticate a person before the Sema
+CLI can run.
+
+Do not put private or sensitive operational material in this repository.
+
+Application-specific authentication belongs in the application repository that
+owns it.