@orkastery/cli 0.5.3 → 0.6.0

package/adapters/claude-code/mods/ork-mesa/types/index.d.ts

@@ -0,0 +1,131 @@
+// Contrato do estado da Mesa do Dono (`ork-mesa`, RM-059 fatia F5; ficha M4 do plano dos mods). Sem import nem
+// referencia, como o motor exige de um contrato: as chaves de `$.state` que a Mesa usa ficam declaradas aqui. A
+// Mesa le o nucleo pela ponte (`$.ork.retrato` e `$.ork.ler`) e por tres ferramentas MCP; nada aqui e resposta
+// do dono, e nenhum campo guarda a opcao que o dono escolheu.
+
+/** Uma alternativa de um pedido, como a Mesa a mostra: letra no `ork.hitl/v2`, numero no `ork.hitl/v1`. */
+export type MesaAlternativa = {
+  chave: string
+  texto: string
+  acao: string
+  /** O que acontece se escolher, em uma linha (so no v2). */
+  consequencia: string | null
+  recomendada: boolean
+  /** O porque da recomendada (so no v2). */
+  porque: string | null
+}
+
+/** A oferta do canal `claude-code` para o pedido, lida do `ork_hitl_pending`; sem leitura, desconhecida. */
+export type MesaCanal = 'disponivel' | 'indisponivel' | 'desconhecido'
+
+/** Um pedido aberto que espera o dono, montado do pulse e conferido no `ork_hitl_pending`. */
+export type MesaPergunta = {
+  thread: string
+  fase: string | null
+  modo: string | null
+  pedidoId: string
+  codigo: string | null
+  contrato: 'ork.hitl/v1' | 'ork.hitl/v2'
+  alvo: 'gate' | 'session'
+  motivo: string
+  pergunta: string
+  /** A recomendacao em texto, como o nucleo a escreve. */
+  recomendacao: string
+  alternativas: MesaAlternativa[]
+  irreversivel: boolean
+  ato: string | null
+  tipoDeResposta: string | null
+  respostaAceita: string | null
+  dependenciaTecnica: boolean
+  acaoAoExpirar: string | null
+  prazo: string | null
+  prazoLocal: string | null
+  desdeEm: string | null
+  /** O estado do pedido no nucleo (`aberto`, `esperar`, `escalar`, `seguir-recomendada`); `desconhecido` sem conferir. */
+  estado: string
+  /** O pedido foi conferido agora no `ork_hitl_pending`; sem isso a Mesa nao decide nem oferece o Decidir. */
+  conferida: boolean
+  canalClaudeCode: MesaCanal
+  /** O que o dono digita pelo Telegram ou no terminal, quando o dialogo nao serve. */
+  reserva: string | null
+}
+
+/** Uma parada sem pedido ou um impedimento que so o dono resolve: so leitura. */
+export type MesaOutro = {
+  chave: string
+  thread: string | null
+  fase: string | null
+  motivo: string
+  texto: string
+  recomendacao: string
+  comando: string
+  desdeEm: string | null
+  impedimento: boolean
+}
+
+/** Uma decisao que a fabrica (ou a Mesa) tomou pelo dono, como o pulse a traz. */
+export type MesaDecisao = {
+  id: string
+  thread: string
+  fase: string
+  em: string
+  decidido: string
+  porque: string
+  comoMudar: string
+  custoAgora: string
+  custoDepois: string
+  quemDecidiu: string
+  /** A decisao que esta desfaz, quando desfaz uma. */
+  reverte: string | null
+  /** A decisao posterior que desfez esta, quando ha. */
+  revertidaPor: string | null
+  /** Ainda nao mostrada ao dono pela Mesa (registro do mostrado da ponte), das ultimas 24 h e nao revertida. */
+  nova: boolean
+}
+
+export type MesaFila = {
+  perguntas: MesaPergunta[]
+  outros: MesaOutro[]
+  decisoes: MesaDecisao[]
+  /** Quantas decisoes a janela do pulse tinha; o painel mostra so as primeiras. */
+  totalDeDecisoes: number
+  lidoEm: number | null
+  erro: string | null
+  /** O que nao saiu inteiro na ultima leitura (uma conferencia, a faixa, o registro): o painel mostra cada um. */
+  avisos: string[]
+}
+
+/** O Decidir de um pedido: o dialogo pedido ao nucleo e o que ele devolveu. */
+export type MesaDecidindo = {
+  estado: 'abrindo' | 'respondido' | 'sem-resposta' | 'erro'
+  texto: string
+  em: number
+}
+
+/**
+ * A decisao obvia que a Mesa pediu ao nucleo: `registrada` quando ele aceitou ou o pulse a mostra; `incerta` quando a
+ * chamada falhou ou passou do prazo e a escrita pode ter chegado (a proxima leitura do pulse decide); `recusada` quando
+ * a leitura seguinte nao a mostra.
+ */
+export type MesaObvia = {
+  estado: 'registrada' | 'incerta' | 'recusada'
+  texto: string
+  em: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'ork-mesa': {
+      /** A fila lida do nucleo. */
+      fila: MesaFila
+      /** A thread que o `/mesa <thread>` pediu; `null` mostra todas. */
+      foco: string | null
+      /** A pagina do lote de perguntas, de cinco em cinco. */
+      pagina: number
+      /** O Decidir de cada pedido, pelo id do pedido. */
+      decidindo: Record<string, MesaDecidindo>
+      /** As decisoes obvias desta sessao, pelo id do pedido. */
+      obvias: Record<string, MesaObvia>
+    }
+  }
+}

package/adapters/claude-code/mods/ork-pista/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "ork-pista",
+  "version": "0.1.0",
+  "description": "Pista de Entrega do Orkastery no Claude Code: do CHECK verde ao merge, cada entrega numa pista com a prova de cada etapa (bundle, branch publicada, PR, CI ork-verify, conflito com a base e ship_done) e o próximo passo que o núcleo declara. Publica só pelo ork ship publicar, no modo que já autoriza o push; nunca faz merge nem tag.",
+  "author": {
+    "name": "Orkastery contributors",
+    "url": "https://github.com/orkastery"
+  },
+  "homepage": "https://orkastery.com/",
+  "repository": "https://github.com/orkastery/orkastery",
+  "license": "MIT",
+  "types": "./types/index.d.ts",
+  "dependencies": ["ork-ponte"]
+}

package/adapters/claude-code/mods/ork-pista/hooks/acoes.ts

@@ -0,0 +1,71 @@
+// Os botoes da Pista (RM-059, fatia F7, T7.3; D6 da thread ork-rm059pista). Modulo puro: o botao que o nucleo declara
+// para cada pista, o argv dos dois comandos que um botao chama e a leitura do resultado de cada um. Botao so existe
+// quando o nucleo declara a acao com `disponivel`, e o argv sai sempre daqui, nunca do texto que veio no JSON: a Pista
+// so publica pelo `ork ship publicar` (que so age em #Auto e #Maestro) e so registra pelo `ork ship registrar-pr`.
+import type { PistaAcao, PistaLinha } from '../types'
+import { exigirThread, jsonDaSaida, umaLinha } from './pista'
+import type { SaidaDoProcesso } from './pista'
+
+export type AcaoDoBotao = PistaAcao['acao']
+
+/** O rotulo de cada botao no painel. */
+export const ROTULO_DO_BOTAO: Readonly<Record<AcaoDoBotao, string>> = { publicar: 'Publicar', registrar: 'Registrar a entrega' }
+
+/** O argv do `ork ship publicar`, sem flag de autorizacao: quem decide se o modo autoriza o push e o nucleo. */
+export function argvDoPublicar(thread: string): string[] {
+  return ['ork', 'ship', 'publicar', exigirThread(thread), '--json']
+}
+
+/** O argv do `ork ship registrar-pr` da thread: o nucleo confere o merge na base e o CI antes de gravar o `ship_done`. */
+export function argvDoRegistro(thread: string): string[] {
+  return ['ork', 'ship', 'registrar-pr', exigirThread(thread), '--json']
+}
+
+/**
+ * O botao da pista (D6): so `publicar`, no modo que ja autoriza o push, e `registrar`, e so quando o nucleo os declara
+ * disponiveis. Fora disso, nenhum botao: o proximo passo fica como texto, com o comando para o dono.
+ */
+export function botaoDaPista(l: PistaLinha): AcaoDoBotao | null {
+  if (!l.proximo.disponivel) return null
+  if (l.proximo.acao === 'publicar') return l.publicavel ? 'publicar' : null
+  if (l.proximo.acao === 'registrar') return 'registrar'
+  return null
+}
+
+export type ResultadoDoBotao = { estado: 'feita' | 'recusada' | 'falhou'; texto: string }
+
+const curto = (sha: unknown) => (typeof sha === 'string' && /^[0-9a-f]{7,40}$/.test(sha) ? sha.slice(0, 7) : '-')
+const texto = (v: unknown, teto = 300) => (typeof v === 'string' ? umaLinha(v, teto) : '')
+
+/** O resultado do `ork ship publicar --json` (`ork.ship-publicar/v1`), numa linha para o painel. */
+export function lerPublicacao(saida: SaidaDoProcesso): ResultadoDoBotao {
+  const r = jsonDaSaida(saida, 'ork ship publicar') as Record<string, unknown> | null
+  if (!r || typeof r !== 'object' || r.contrato !== 'ork.ship-publicar/v1') {
+    return { estado: 'falhou', texto: 'a saída do ork ship publicar não é o contrato ork.ship-publicar/v1' }
+  }
+  const pr = (r.pr ?? null) as { numero?: unknown; criado?: unknown } | null
+  const numero = pr && Number.isSafeInteger(pr.numero) ? `PR #${pr.numero as number}` : 'sem PR'
+  if (r.acao === 'publicou') {
+    return { estado: 'feita', texto: `publicada no HEAD ${curto(r.head)}, push provado pelo ls-remote; ${numero} ${pr?.criado === true ? 'aberto agora' : 'reaproveitado'}` }
+  }
+  if (r.acao === 'ja-publicada') {
+    return { estado: 'feita', texto: `já estava publicada no HEAD ${curto(r.head)}; ${numero}${texto(r.correcao) ? `; ${texto(r.correcao)}` : ''}` }
+  }
+  if (r.acao === 'recusada') {
+    const correcao = texto(r.correcao, 400)
+    return { estado: 'recusada', texto: `recusada (${texto(r.motivo, 60) || 'sem motivo'}): ${texto(r.detalhe) || 'sem detalhe'}${correcao ? `; ${correcao}` : ''}` }
+  }
+  return { estado: 'falhou', texto: `o ork ship publicar respondeu ${texto(r.acao, 40) || 'sem ação'}` }
+}
+
+/** O resultado do `ork ship registrar-pr <thread> --json` (uma lista de entregas), numa linha para o painel. */
+export function lerRegistro(saida: SaidaDoProcesso, thread: string): ResultadoDoBotao {
+  const lista = jsonDaSaida(saida, 'ork ship registrar-pr')
+  const item = Array.isArray(lista) ? (lista as Array<Record<string, unknown> | null>).find(x => x?.thread === thread) : undefined
+  if (!item) return { estado: 'falhou', texto: `o ork ship registrar-pr não respondeu pela thread ${thread}` }
+  const motivo = texto(item.motivo) || 'sem motivo'
+  if (item.acao === 'registrou') return { estado: 'feita', texto: `ship_done registrado: ${motivo}` }
+  if (item.acao === 'ja-registrada') return { estado: 'feita', texto: `a entrega já estava registrada: ${motivo}` }
+  if (item.acao === 'sem-merge' || item.acao === 'recusada') return { estado: 'recusada', texto: `${String(item.acao)}: ${motivo}` }
+  return { estado: 'falhou', texto: `o ork ship registrar-pr respondeu ${texto(item.acao, 40) || 'sem ação'}` }
+}

package/adapters/claude-code/mods/ork-pista/hooks/ci.ts

@@ -0,0 +1,121 @@
+// O CI de cada pista (RM-059, fatia F7, T7.4; D7 da thread ork-rm059pista). Modulo puro: o argv da consulta ao nucleo
+// (`ork ci status --sha <sha> --json`, contrato `ork.ci-status/v2`; a v1 dos nucleos anteriores continua lida), a
+// leitura dela, as pistas que um evento do GitHub cita, as que o relogio de reserva consulta e a etapa de CI que o
+// painel mostra com a leitura mais nova. O evento so dispara a consulta: o conteudo dele nunca vira estado, e quem diz o
+// CI e o check do nucleo no sha exato.
+import type { PistaCi, PistaEstadoDaEtapa, PistaLinha, PistaQuadro } from '../types'
+import { jsonDaSaida, umaLinha } from './pista'
+import type { SaidaDoProcesso } from './pista'
+
+/** A reserva sem evento: a cada 2 min com o painel a vista, a cada 10 min escondido. */
+export const INTERVALO_DO_CI_A_VISTA_MS = 2 * 60000
+export const INTERVALO_DO_CI_ESCONDIDO_MS = 10 * 60000
+const SHA = /^[0-9a-f]{40}$/
+const ESTADOS: readonly PistaCi['estado'][] = ['success', 'pending', 'failure', 'missing', 'unavailable', 'disabled']
+
+/** O argv da consulta do CI no sha exato do head do PR, nunca por ref nem prefixo. */
+export function argvDoCi(sha: string): string[] {
+  if (typeof sha !== 'string' || !SHA.test(sha)) throw new Error('ork-pista: sha invalido para o ork ci status')
+  return ['ork', 'ci', 'status', '--sha', sha, '--json']
+}
+
+/** Os contratos do `ork ci status --json` que a Pista le: a v2 (forja, fonte e produtor) e a v1 de antes. */
+const CONTRATOS_DO_CI: readonly string[] = ['ork.ci-status/v1', 'ork.ci-status/v2']
+
+/**
+ * A saida do `ork ci status --sha <sha> --json`: o comando sai 0 so com o check verde, e o JSON vem nos dois casos.
+ * Leitura de outro sha nao vale para a pista.
+ */
+export function lerCi(saida: SaidaDoProcesso, sha: string, agora: number, motivo: PistaCi['motivo']): PistaCi {
+  const r = jsonDaSaida(saida, 'ork ci status') as Record<string, unknown> | null
+  if (!r || typeof r !== 'object' || !CONTRATOS_DO_CI.includes(r.schema as string) || !ESTADOS.includes(r.state as PistaCi['estado'])) {
+    throw new Error('a saída do ork ci status não é o contrato ork.ci-status (v1 ou v2)')
+  }
+  if (r.sha !== sha) throw new Error(`o ork ci status respondeu pelo commit ${umaLinha(r.sha, 40)}, e não pelo head ${sha.slice(0, 7)}`)
+  const estado = r.state as PistaCi['estado']
+  const contexto = typeof r.context === 'string' && r.context ? umaLinha(r.context, 60) : 'ork-verify'
+  const curto = sha.slice(0, 7)
+  const texto = estado === 'success' ? `check ${contexto} verde no head ${curto}`
+    : estado === 'failure' ? `check ${contexto} vermelho no head ${curto}`
+    : estado === 'pending' ? `check ${contexto} em andamento no head ${curto}`
+    : estado === 'missing' ? `o check ${contexto} ainda não apareceu no head ${curto}`
+    : estado === 'disabled' ? 'CI não exigido pelo manifesto'
+    : `o CI não foi lido: ${umaLinha(r.detail, 160) || 'sem detalhe'}`
+  const url = typeof r.url === 'string' && /^https:\/\/\S+$/.test(r.url) ? umaLinha(r.url, 300) : null
+  return { sha, estado, texto, url, lidoEm: agora, motivo }
+}
+
+/** A pista com PR aberto cujo CI a leitura da pista ainda nao fechou (nem verde nem vermelho). */
+export function precisaDoCi(l: PistaLinha): boolean {
+  const etapa = l.etapas.find(e => e.id === 'ci')
+  return l.pr?.estado === 'aberto' && SHA.test(l.pr.head) && (etapa?.estado === 'pendente' || etapa?.estado === 'nao-lida')
+}
+
+/** As pistas que o relogio de reserva consulta agora: as que precisam, sem leitura do head atual dentro do intervalo. */
+export function vencidasDoCi(linhas: readonly PistaLinha[], ci: Readonly<Record<string, PistaCi>>, agora: number, intervalo: number): string[] {
+  return linhas.filter(l => {
+    if (!precisaDoCi(l)) return false
+    const lido = ci[l.thread]
+    return !lido || lido.sha !== l.pr?.head || agora - lido.lidoEm >= intervalo
+  }).map(l => l.thread)
+}
+
+/**
+ * As pistas que um evento do GitHub cita, so pelos campos que o servidor assere (fora de `untrustedKeys`): o PR (o
+ * numero, ou `dono/repo#N`), a branch ou o sha. Evento de outra fonte, ou que nao cita pista nenhuma, nao consulta nada.
+ */
+export function pistasDoEvento(evento: unknown, linhas: readonly PistaLinha[]): string[] {
+  if (!evento || typeof evento !== 'object') return []
+  const e = evento as { source?: unknown; data?: unknown; untrustedKeys?: unknown }
+  if (e.source !== 'github' || !e.data || typeof e.data !== 'object') return []
+  const deTerceiros = new Set(Array.isArray(e.untrustedKeys) ? e.untrustedKeys.map(String) : [])
+  const numeros = new Set<number>()
+  const textos = new Set<string>()
+  for (const [chave, valor] of Object.entries(e.data as Record<string, unknown>)) {
+    if (deTerceiros.has(chave)) continue
+    if (typeof valor === 'number' && Number.isSafeInteger(valor) && valor > 0 && /^(pr|number|pull_request|pull)$/i.test(chave)) numeros.add(valor)
+    if (typeof valor !== 'string') continue
+    const pr = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+#(\d{1,9})$/.exec(valor.trim()) ?? (/^(pr|number|pull_request|pull)$/i.test(chave) ? /^#?(\d{1,9})$/.exec(valor.trim()) : null)
+    if (pr) numeros.add(Number(pr[1]))
+    textos.add(valor.trim())
+  }
+  return linhas.filter(l => (l.pr && numeros.has(l.pr.numero)) || textos.has(l.branch) || (!!l.head && textos.has(l.head)) ||
+    (!!l.pr && textos.has(l.pr.head))).map(l => l.thread)
+}
+
+const ETAPA_DO_CI: Readonly<Record<PistaCi['estado'], PistaEstadoDaEtapa>> = {
+  success: 'feita', failure: 'falhou', pending: 'pendente', missing: 'pendente', unavailable: 'nao-lida', disabled: 'nao-se-aplica',
+}
+
+/** A consulta leu o check no head: `unavailable` (a consulta falhou) e `disabled` (o CI nao e exigido) nao leram nada. */
+function leuOCheck(lido: PistaCi): boolean {
+  return lido.estado !== 'unavailable' && lido.estado !== 'disabled'
+}
+
+/**
+ * A pista com a leitura do CI mais nova por cima da etapa da leitura da pista, so quando ela e do head do PR aberto. A
+ * consulta que nao leu nada nunca apaga o que o nucleo ja leu: a etapa fica como o nucleo disse, com a falha ao lado.
+ */
+export function comCi(q: PistaQuadro, ci: Readonly<Record<string, PistaCi>>): PistaQuadro {
+  return {
+    ...q,
+    linhas: q.linhas.map(l => {
+      const lido = ci[l.thread]
+      if (!lido || l.pr?.estado !== 'aberto' || lido.sha !== l.pr.head) return l
+      if (!leuOCheck(lido)) {
+        return { ...l, etapas: l.etapas.map(e => (e.id === 'ci' ? { ...e, texto: `${e.texto} (consulta: ${lido.texto})` } : e)) }
+      }
+      const origem = lido.motivo === 'evento' ? ' (pelo evento do GitHub)' : ''
+      return { ...l, etapas: l.etapas.map(e => (e.id === 'ci' ? { id: 'ci', estado: ETAPA_DO_CI[lido.estado], texto: `${lido.texto}${origem}` } : e)) }
+    }),
+  }
+}
+
+/**
+ * A leitura nova diz do CI outra coisa que a etapa da pista: o CI fechou, ou mudou depois de uma rodada nova. O proximo
+ * passo do nucleo muda com ele, e a pista inteira e relida. A consulta que nao leu nada nao muda nada.
+ */
+export function mudouOCi(l: PistaLinha, lido: PistaCi): boolean {
+  if (!leuOCheck(lido) || l.pr?.estado !== 'aberto' || lido.sha !== l.pr.head) return false
+  return l.etapas.find(e => e.id === 'ci')?.estado !== ETAPA_DO_CI[lido.estado]
+}

package/adapters/claude-code/mods/ork-pista/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.tsx"]
+}