expxdev 0.1.0 → 0.2.0

package/dist/teste/repo-fixture.d.ts

@@ -14,6 +14,13 @@ export type OpcoesRepo = {
     layout?: Layout;
     /** Conteúdo extra do SKILL.md, para fixtures que precisam de um corpo específico. */
     corpo?: string;
+    /**
+     * Hooks da skill, gravados em `.claude/hooks/` com bit de execução. O memox é
+     * a primeira skill do catálogo que traz hooks; antes dele nenhuma trazia.
+     */
+    hooks?: readonly string[];
+    /** Arquivos de `assets/` da skill, por nome. É onde mora o motor do memox. */
+    assets?: Readonly<Record<string, string>>;
 };
 /**
  * Onde o SKILL.md e os comandos ficam em cada layout. `embutido` é o do

package/dist/teste/repo-fixture.js

@@ -35,6 +35,24 @@ export function criarRepoSkill(op) {
         `---\nname: ${op.nome}\ndescription: Skill de fixture ${op.nome} para a suite do expx-cli\n---\n\n# ${op.nome}\n\nDetalhe em \`references/01.md\`.\n`);
     writeFileSync(join(raiz, skill, "references", "01.md"), `# referencia de ${op.nome}\n`);
     writeFileSync(join(raiz, comandos, `${op.nome}.md`), `---\ndescription: comando ${op.nome}\n---\n\nInvoque a skill \`${op.nome}\`.\n`);
+    // Os hooks nascem executáveis: o README do memox manda `chmod +x`, e um hook
+    // sem o bit sai `0` em silêncio — indistinguível de "nada a injetar".
+    if (op.hooks !== undefined && op.hooks.length > 0) {
+        const dirHooks = join(raiz, ".claude", "hooks");
+        mkdirSync(dirHooks, { recursive: true });
+        for (const h of op.hooks) {
+            writeFileSync(join(dirHooks, h), `#!/usr/bin/env bash\n# hook de fixture ${h}\nexit 0\n`, {
+                mode: 0o755,
+            });
+        }
+    }
+    if (op.assets !== undefined) {
+        const dirAssets = join(raiz, skill, "assets");
+        mkdirSync(dirAssets, { recursive: true });
+        for (const [nome, conteudo] of Object.entries(op.assets)) {
+            writeFileSync(join(dirAssets, nome), conteudo);
+        }
+    }
     git(raiz, "init", "-q", "-b", "main");
     git(raiz, "add", "-A");
     git(raiz, "commit", "-q", "-m", `${op.nome}: commit inicial`);

package/dist/teste/repo-fixture.js.map

@@ -1 +1 @@
-{"version":3,"file":"repo-fixture.js","sourceRoot":"","sources":["../../src/teste/repo-fixture.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"repo-fixture.js","sourceRoot":"","sources":["../../src/teste/repo-fixture.ts"],"names":[],"mappings":"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"}

package/nucleo/README.md

@@ -0,0 +1,79 @@
+# Núcleo compartilhado
+
+O que as skills do método precisam ter **igual**, escrito uma vez só.
+
+## O que tem aqui
+
+| Arquivo | O que é |
+|---|---|
+| `hooks/expx-rastro.sh` | O rastro de eventos, os modos de hook e o `trabalho_id` |
+
+## Como chega até um projeto
+
+Por **cópia**, nunca por dependência.
+
+Nenhum dos repositórios de skill tem `package.json` — eles são plugins
+instalados sozinhos, e cada projeto precisa rodar de forma independente. Uma
+biblioteca importada em tempo de execução quebraria exatamente isso.
+
+Então: a fonte é este diretório, o `expx init` copia (`montarPlugin` leva
+`nucleo/` junto com o plugin), e o que chega ao projeto é um arquivo em disco.
+Sem `npm install`, sem runtime compartilhado, sem rede.
+
+## Como usar num hook
+
+A ferramenta é **parâmetro**, definido antes do `source`:
+
+```sh
+EXPX_FERRAMENTA=mergex
+. "$(dirname "$0")/../nucleo/hooks/expx-rastro.sh"
+
+MODO="$(expx_modo "$RAIZ" git-perigoso seguranca)"
+[ "$MODO" = "desligado" ] && exit 0
+
+expx_rastro_grava "$RAIZ" acao_bloqueada hook bloqueado "commit na main" '[]' \
+  '"hook":"git-perigoso"'
+```
+
+Variáveis que o rastro lê, todas opcionais:
+
+| Variável | Efeito |
+|---|---|
+| `EXPX_FERRAMENTA` | o campo `ferramenta` da linha (**defina sempre**) |
+| `EXPX_TRABALHO_ID` | vence a detecção automática |
+| `EXPX_FASE` / `EXPX_TASK` | preenchem `fase` e `task` (JSON: com aspas) |
+| `EXPX_AGENTE` | o subagente; sem ela, `principal` |
+
+## Por que existe
+
+Cada skill tinha a sua implementação do rastro — quatro no total, em duas
+linguagens. Não eram cópias que divergiram: eram **reescritas**, porque o
+`comum/rastro.sh` de cada repositório trazia o nome da ferramenta cravado no
+código (`"ferramenta":"sprintx"`), e um arquivo que se identifica não pode ser
+compartilhado.
+
+E já divergiam em produção, antes mesmo de o painel ler o rastro:
+
+- chave extra no meio do objeto, quebrando a verificação de uma skill irmã
+- `agente` ora `null`, ora `"principal"`, para o mesmo caso
+- três estratégias diferentes para descobrir o `trabalho_id`
+- dois conjuntos de modos: uma skill não conhecia `desligado` e continuava
+  rodando depois de alguém pedir para desligá-la
+- um leitor de lock com o nome do arquivo errado, falhando em silêncio
+
+## Adoção
+
+Incremental, uma skill por vez. Uma skill migra quando trocar o `source` do seu
+`comum/rastro.sh` por este arquivo e renomear as chamadas (`rastro_*` →
+`expx_*`). Enquanto não migra, continua com a cópia própria — que é o ponto de
+distribuir por cópia: nada quebra enquanto a migração não acontece.
+
+O que garante que as duas não divirjam no meio do caminho é o validador:
+`expx doctor` lê `docs/eventos/*.jsonl` e aponta toda linha fora do contrato,
+seja qual for a implementação que a escreveu.
+
+## Contratos
+
+- [`CONVENCOES.md`](../docs/contrato/CONVENCOES.md) — R1 a R14, o documento raiz
+- [`CONTRATO-expx-eventos.md`](../docs/contrato/CONTRATO-expx-eventos.md) — a linha do rastro, hooks e agentes
+- [`CONTRATO-expx-schema-v1.md`](../docs/contrato/CONTRATO-expx-schema-v1.md) — o frontmatter de estado

package/nucleo/hooks/expx-rastro.sh

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+# expx-rastro.sh — o rastro de eventos do metodo Expx, uma vez so.
+#
+# Implementa o contrato `expx-eventos` v1 e as convencoes R1-R14
+# (docs/contrato/CONVENCOES.md e CONTRATO-expx-eventos.md).
+#
+# NAO E EXECUTAVEL: os hooks fazem `source` deste arquivo.
+#
+# ---------------------------------------------------------------------------
+# Por que este arquivo existe
+#
+# Cada skill tinha a sua propria implementacao do rastro — quatro no total, em
+# duas linguagens. Nao eram copias que divergiram: eram reescritas, porque o
+# `comum/rastro.sh` de cada repo trazia o nome da ferramenta CRAVADO no codigo
+# (`"ferramenta":"sprintx"`) e por isso nao dava para compartilhar. Elas ja
+# divergiam em producao: chave extra no meio do objeto, `agente` ora null ora
+# "principal", tres estrategias de trabalho_id, dois conjuntos de modos.
+#
+# Aqui a ferramenta e PARAMETRO. Defina `EXPX_FERRAMENTA` antes do source:
+#
+#   EXPX_FERRAMENTA=mergex
+#   . "$(dirname "$0")/expx-rastro.sh"
+#
+# ---------------------------------------------------------------------------
+# Como este arquivo chega ate um projeto
+#
+# Por COPIA, nunca por dependencia. O `expx init` copia; cada repositorio
+# continua rodando sozinho, com o que tem em disco, sem `npm install` e sem
+# runtime compartilhado. A fonte e o plugin; a copia e versionada com a skill.
+#
+# ---------------------------------------------------------------------------
+# Regras do contrato que este arquivo materializa
+#   1. Rapido       — sem rede, sem parser externo pesado.
+#   3. Falha aberta — toda funcao retorna 0 mesmo sem conseguir gravar.
+#   6. Sem estado   — tudo sai de arquivo que ja existe.
+#   7. Sempre grava — inclusive quando permite.
+
+# A ferramenta e obrigatoria, mas a ausencia NAO derruba o hook (regra 3):
+# cai para "desconhecida", que o validador aponta em vez de sumir em silencio.
+: "${EXPX_FERRAMENTA:=desconhecida}"
+
+# ---------------------------------------------------------------- util basica
+
+# Raiz do repositorio: sobe ate achar .git; sem .git, o cwd.
+expx_raiz() {
+  local d="${1:-$PWD}"
+  while [ "$d" != "/" ]; do
+    [ -d "$d/.git" ] && { printf '%s' "$d"; return 0; }
+    d="$(dirname "$d")"
+  done
+  printf '%s' "${1:-$PWD}"
+}
+
+# Escapa uma string para caber num JSON string literal.
+# A barra invertida vem primeiro, senao escapamos o que ja foi escapado.
+expx_json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//	/\\t}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\n'/\\n}"
+  printf '%s' "$s"
+}
+
+# Le uma chave de topo do JSON que o harness manda no stdin do hook.
+# Com jq quando existe; sem jq, um grep tolerante. Nunca falha.
+expx_json_get() {
+  local json="$1" chave="$2"
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$json" | jq -r --arg k "$chave" '.[$k] // empty' 2>/dev/null
+    return 0
+  fi
+  printf '%s' "$json" \
+    | grep -o "\"$chave\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" \
+    | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//'
+}
+
+# Le uma chave aninhada em tool_input (ex.: file_path).
+expx_tool_input_get() {
+  local json="$1" chave="$2"
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$json" | jq -r --arg k "$chave" '.tool_input[$k] // empty' 2>/dev/null
+    return 0
+  fi
+  printf '%s' "$json" \
+    | grep -o "\"$chave\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" \
+    | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//'
+}
+
+# ------------------------------------------------------------- trabalho_id
+
+# O trabalho corrente.
+#
+# UMA estrategia, em ordem de autoridade — antes eram tres, uma por skill, que
+# davam respostas diferentes no mesmo repositorio na mesma execucao:
+#
+#   1. EXPX_TRABALHO_ID, quando a skill ja sabe qual e
+#   2. .expx/expx-lock.json, que o CLI mantem
+#   3. o ORQUESTRADOR.md mais recente, nos dois layouts de pasta
+#   4. "sem-trabalho"
+#
+# O nome do lock e `expx-lock.json` (src/nucleo/lock.ts). Ler `lock.json` sem
+# o prefixo devolve "sem-trabalho" para sempre, em silencio — a falha aqui e
+# aberta por desenho, entao o erro nunca se anuncia.
+expx_trabalho_id() {
+  local raiz="$1" v=""
+
+  if [ -n "${EXPX_TRABALHO_ID:-}" ]; then
+    printf '%s' "$EXPX_TRABALHO_ID" | tr -c 'A-Za-z0-9._-' '-' | cut -c1-64
+    return 0
+  fi
+
+  local lock="$raiz/.expx/expx-lock.json"
+  if [ -f "$lock" ]; then
+    if command -v jq >/dev/null 2>&1; then
+      v="$(jq -r '.trabalho_id // empty' "$lock" 2>/dev/null)"
+    else
+      v="$(grep -o '"trabalho_id"[[:space:]]*:[[:space:]]*"[^"]*"' "$lock" 2>/dev/null \
+           | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')"
+    fi
+    if [ -n "$v" ]; then
+      printf '%s' "$v" | tr -c 'A-Za-z0-9._-' '-' | cut -c1-64
+      return 0
+    fi
+  fi
+
+  # Os dois layouts: o novo (docs/<skill>/features|ocorrencias/<slug>/) e o
+  # antigo (docs/<slug>/), que as skills declaram continuar suportando.
+  #
+  # `find` em vez de glob: no zsh um padrao sem match ABORTA a funcao (nomatch),
+  # e o hook perderia o trabalho_id no shell de metade dos usuarios. O -maxdepth
+  # 4 cobre os dois layouts sem varrer o repositorio inteiro.
+  local f mais_novo=""
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    if [ -z "$mais_novo" ] || [ "$f" -nt "$mais_novo" ]; then mais_novo="$f"; fi
+  done <<EOF
+$(find "$raiz/docs" -maxdepth 4 -name ORQUESTRADOR.md -type f 2>/dev/null)
+EOF
+  if [ -n "$mais_novo" ]; then
+    basename "$(dirname "$mais_novo")"
+    return 0
+  fi
+
+  printf 'sem-trabalho'
+}
+
+# ------------------------------------------------------------------ modo
+
+# Modo de um hook: aviso | bloqueio | desligado.
+#
+# Uso: expx_modo <raiz> <hook> [tipo]     tipo: metodo (padrao) | seguranca
+#
+# Os TRES modos sao obrigatorios. Reconhecer so dois e cair no padrao diante do
+# terceiro faz o hook continuar rodando depois de alguem pedir para desliga-lo.
+#
+# O padrao sai do `tipo`: hook de seguranca nasce em bloqueio e NUNCA e
+# rebaixado por ausencia de configuracao; hook de metodo nasce em aviso. So um
+# "desligado" explicito desliga um hook de seguranca.
+expx_modo() {
+  local raiz="$1" hook="$2" tipo="${3:-metodo}" m=""
+  local cfg="$raiz/.expx/hooks.json"
+  local padrao='aviso'
+  [ "$tipo" = "seguranca" ] && padrao='bloqueio'
+
+  [ -f "$cfg" ] || { printf '%s' "$padrao"; return 0; }
+
+  if command -v jq >/dev/null 2>&1; then
+    # `.modos[...]` e a forma antiga, aceita para nao quebrar quem escreveu o
+    # arquivo a mao antes do formato atual.
+    m="$(jq -r --arg h "$hook" '.hooks[$h].modo // .modos[$h] // empty' "$cfg" 2>/dev/null)"
+  else
+    m="$(grep -o "\"$hook\"[[:space:]]*:[[:space:]]*{[^}]*}" "$cfg" 2>/dev/null \
+         | grep -o '"modo"[[:space:]]*:[[:space:]]*"[^"]*"' \
+         | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')"
+  fi
+
+  case "$m" in
+    aviso|bloqueio|desligado) printf '%s' "$m" ;;
+    *)                       printf '%s' "$padrao" ;;
+  esac
+}
+
+# ---------------------------------------------------------------- gravacao
+
+# expx_rastro_grava <raiz> <evento> <origem> <resultado> <detalhe> [arquivos_json] [extras_json]
+#
+# Grava UMA linha em docs/eventos/<trabalho_id>.jsonl.
+#
+# As DOZE chaves obrigatorias saem sempre todas, na ordem do contrato, e chave
+# sem valor vai como null — nunca omitida (R6). As extras declaradas (`hook`,
+# `faixa`) vao DEPOIS das doze, em `extras_json`, nunca no meio: quem valida
+# procura as doze por contencao, e uma chave no meio do objeto ja quebrou a
+# verificacao de uma skill irma.
+#
+# Falha aberta: erro aqui e engolido. Um hook nunca trava o trabalho por nao
+# conseguir escrever o proprio rastro.
+expx_rastro_grava() {
+  local raiz="$1" evento="$2" origem="$3" resultado="$4" detalhe="$5"
+  local arquivos="${6:-[]}" extras="${7:-}"
+
+  {
+    local dir="$raiz/docs/eventos"
+    mkdir -p "$dir" 2>/dev/null || return 0
+
+    local tid; tid="$(expx_trabalho_id "$raiz")"
+    local arq="$dir/$tid.jsonl"
+
+    # Rotacao: acima de 5 MB o arquivo vira <trabalho_id>.1.jsonl (contrato).
+    if [ -f "$arq" ]; then
+      local tam
+      tam=$(wc -c < "$arq" 2>/dev/null | tr -d ' ')
+      if [ -n "$tam" ] && [ "$tam" -gt 5242880 ] 2>/dev/null; then
+        mv -f "$arq" "$dir/$tid.1.jsonl" 2>/dev/null || true
+      fi
+    fi
+
+    local ts; ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    local linha
+    linha="{\"ts\":\"$ts\""
+    linha="$linha,\"expx_eventos\":1"
+    linha="$linha,\"trabalho_id\":\"$(expx_json_escape "$tid")\""
+    linha="$linha,\"ferramenta\":\"$EXPX_FERRAMENTA\""
+    linha="$linha,\"origem\":\"$origem\""
+    linha="$linha,\"evento\":\"$evento\""
+    linha="$linha,\"fase\":${EXPX_FASE:-null}"
+    linha="$linha,\"task\":${EXPX_TASK:-null}"
+    # Sem subagente o valor e "principal", nunca null: "foi o principal" e
+    # informacao, nao ausencia.
+    linha="$linha,\"agente\":\"${EXPX_AGENTE:-principal}\""
+    linha="$linha,\"resultado\":\"$resultado\""
+    linha="$linha,\"detalhe\":\"$(expx_json_escape "$detalhe")\""
+    linha="$linha,\"arquivos\":$arquivos"
+    [ -n "$extras" ] && linha="$linha,$extras"
+    linha="$linha}"
+
+    printf '%s\n' "$linha" >> "$arq" 2>/dev/null || true
+  } 2>/dev/null || true
+  return 0
+}
+
+# ------------------------------------------------------------------- saida
+
+# Aviso que CHEGA ao modelo em PostToolUse.
+#
+# Ali o exit 2 nao bloqueia e o stderr NAO volta ao modelo — verificado na
+# documentacao oficial. O unico canal e JSON no stdout. Escrever em stderr num
+# PostToolUse e falha silenciosa.
+expx_aviso_ao_modelo() {
+  printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' \
+    "$1" "$(expx_json_escape "$2")"
+}
+
+# Bloqueio em PreToolUse: exit 2 com o motivo no stderr, que vira a mensagem
+# que o modelo le. Mensagem acionavel: diga o que fazer, nao so o que esta
+# errado.
+expx_bloqueia() {
+  printf '%s\n' "$1" >&2
+  exit 2
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "expxdev",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI do metodo Expx: instala, atualiza e opera o ecossistema de skills, e sobe o painel de operacao",
   "type": "module",
   "bin": {
     "expx": "dist/cli/expx-bin.js",
+    "expxdev": "dist/cli/expx-bin.js",
     "expx-painel": "dist/cli/principal.js"
   },
   "engines": {
@@ -22,6 +23,7 @@
   "files": [
     "dist",
     "ui/dist",
+    "nucleo",
     "README.md",
     "LICENSE"
   ],
@@ -62,12 +64,12 @@
     "painel"
   ],
   "author": "Expx",
-  "homepage": "https://github.com/bittencourtthulio/expx-painel#readme",
+  "homepage": "https://github.com/bittencourtthulio/expxdev#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bittencourtthulio/expx-painel.git"
+    "url": "git+https://github.com/bittencourtthulio/expxdev.git"
   },
   "bugs": {
-    "url": "https://github.com/bittencourtthulio/expx-painel/issues"
+    "url": "https://github.com/bittencourtthulio/expxdev/issues"
   }
 }