@orkastery/cli 0.2.0

package/dist/hosts.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * `ork adapter list|show|install <host>`: instalacao dos adaptadores de Camada 1 (bloco B4).
+ *
+ * O que este modulo faz e deliberadamente pouco: ele COPIA arquivos do produto para onde o
+ * host os procura, renderiza tres placeholders e escreve um recibo. Nenhuma regra de negocio
+ * do Orkastery mora aqui, e nenhum adaptador ganha comportamento na instalacao que ele nao
+ * tenha em disco: o que o builder le em `adapters/<host>/` e o que roda.
+ *
+ * Duas decisoes que carregam peso:
+ *
+ *  - **Uma copia so do catalogo.** O instalador copia de `skills/` e `references/`, sempre da
+ *    mesma raiz, e grava a origem e o sha256 de cada arquivo em `INSTALADO.json`. Duas copias
+ *    do catalogo divergem, e a divergencia so aparece quando ja custou uma entrega.
+ *  - **Sobrescrever e decisao, nao efeito colateral.** Arquivo que ja existe diferente do que
+ *    seria escrito faz a instalacao parar e pedir `--force`, listando os arquivos. Instalador
+ *    que apaga edicao alheia em silencio e o mesmo defeito que o guard `git add -A` bloqueia.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDEM_DOS_HOSTS = exports.HOSTS = void 0;
+exports.parseHost = parseHost;
+exports.renderizarArquivo = renderizarArquivo;
+exports.instalarAdaptador = instalarAdaptador;
+exports.tabelaDeHosts = tabelaDeHosts;
+exports.textoDosPitfalls = textoDosPitfalls;
+exports.textoDaInstalacao = textoDaInstalacao;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const catalogo_1 = require("./catalogo");
+const util_1 = require("./util");
+exports.HOSTS = {
+    'claude-code': {
+        host: 'claude-code',
+        descricao: 'Plugin com as 17 skills, 6 subagentes de fase, os comandos /goal ... /master e o guard PreToolUse',
+        destinoPadrao: '.claude',
+        subdir: path.join('plugins', 'orkastery'),
+        levaCatalogo: true,
+        pitfalls: [
+            {
+                titulo: 'manifesto sem os caminhos das skills instala limpo e nao expoe nada',
+                detalhe: 'o plugin auto-descobre skills/<nome>/SKILL.md e para ai: ele nao desce nos buckets (core/, phases/, reviewers/, ...) que este catalogo usa, entao o plugin.json declara os 17 caminhos um a um',
+                prova: 'claude plugin details orkastery   # a contagem precisa bater com os SKILL.md em disco',
+            },
+            {
+                titulo: 'duas copias do catalogo divergem',
+                detalhe: 'a fonte unica e skills/ na raiz do produto; o INSTALADO.json guarda a origem e o sha256 de cada arquivo, e reinstalar com --force ressincroniza. Editar a copia instalada e bandeira vermelha',
+                prova: 'ork adapter install claude-code --dry-run   # mostra o que divergiu do catalogo',
+            },
+            {
+                titulo: 'hook com caminho relativo nao roda, e o guard vira decoracao',
+                detalhe: 'o hooks.json chama node "${CLAUDE_PLUGIN_ROOT}/hooks/ork-guard.js", nunca um caminho relativo ao diretorio de trabalho, que muda a cada worktree de thread',
+                prova: 'echo \'{"tool_name":"Bash","tool_input":{"command":"git add -A"}}\' | node <destino>/hooks/ork-guard.js ; echo "codigo: $?"   # 2 = guard vivo',
+            },
+        ],
+    },
+    hermes: {
+        host: 'hermes',
+        descricao: 'Skill roteadora fina, plugin que a declara e script de abertura de thread',
+        destinoPadrao: '.hermes',
+        subdir: '',
+        levaCatalogo: false,
+        pitfalls: [
+            {
+                titulo: 'ork fora do PATH do host',
+                detalhe: 'o host roda com ambiente mais enxuto que o terminal do builder e ~/.local/bin pode nao estar la; o plugin grava o caminho absoluto e o script honra ORK_BIN',
+                prova: 'ORK_BIN=$(command -v ork) ; "$ORK_BIN" doctor',
+            },
+            {
+                titulo: 'reimplementar o parse da #TAG no host',
+                detalhe: 'duas implementacoes divergem na primeira tag nova, e a divergencia aparece como thread aberta no modo errado, o que ninguem percebe ate a pausa que nao veio',
+                prova: 'ork modos --do-pedido "teste #Maestro"   # a unica fonte do modo',
+            },
+            {
+                titulo: 'validar allowed_modes no host',
+                detalhe: 'um host que recusa o modo antes de chamar o ork recusa com a regra que ele tem em cache, nao com a do manifesto do projeto; deixe o ork thread new recusar, com erro tipado',
+                prova: 'ork thread new "teste" --mode look --dry-run',
+            },
+        ],
+    },
+    openclaw: {
+        host: 'openclaw',
+        descricao: 'openclaw.plugin.json com as tools ork_*, cada uma uma chamada de CLI',
+        destinoPadrao: '.openclaw',
+        subdir: '',
+        levaCatalogo: false,
+        pitfalls: [
+            {
+                titulo: 'placeholder {{ork_bin}} que fica no arquivo',
+                detalhe: 'o host executa o vetor de comando como ele esta: um placeholder nao renderizado vira "comando nao encontrado" em toda tool, e a sessao so descobre depois de ja ter aberto thread na cabeca do agente',
+                prova: 'grep -c "{{" <destino>/openclaw.plugin.json   # precisa devolver 0',
+            },
+            {
+                titulo: 'argumento com espaco quebrado em varios argumentos',
+                detalhe: 'cada tool declara o comando como VETOR, nunca como string de shell, para o pedido do builder chegar inteiro em --prompt; string de shell aqui vira injecao de comando com o texto do builder dentro',
+                prova: 'ork_phase_run com um prompt de varias linhas, conferido em ork phase list <thread>',
+            },
+            {
+                titulo: 'tool que reimplementa regra do nucleo',
+                detalhe: 'toda tool deste plugin e uma chamada de CLI e nada mais; tool nova que precisa de logica e sinal de que a logica pertence ao ork, com teste',
+                prova: 'ork eval   # o corpus reprova host com regra de negocio duplicada',
+            },
+        ],
+    },
+};
+exports.ORDEM_DOS_HOSTS = ['claude-code', 'hermes', 'openclaw'];
+/** Reconhece o nome do host, com os apelidos que o builder costuma digitar. */
+function parseHost(bruto) {
+    const limpo = (bruto ?? '').trim().toLowerCase();
+    if (limpo === 'claude-code' || limpo === 'claude' || limpo === 'claudecode')
+        return 'claude-code';
+    if (limpo === 'hermes')
+        return 'hermes';
+    if (limpo === 'openclaw' || limpo === 'open-claw')
+        return 'openclaw';
+    return null;
+}
+/** Extensoes cujo conteudo passa pela renderizacao de placeholders. */
+const RENDERIZAVEIS = new Set(['.md', '.json', '.sh', '.js', '.yaml', '.yml', '.txt']);
+/** Extensoes que sao instaladas com bit de execucao. */
+const EXECUTAVEIS = new Set(['.sh', '.js']);
+function sha256(conteudo) {
+    return (0, node_crypto_1.createHash)('sha256').update(conteudo).digest('hex');
+}
+function listarArquivos(dir, prefixo = '') {
+    const achados = [];
+    for (const entrada of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const origem = path.join(dir, entrada.name);
+        const relativo = path.posix.join(prefixo, entrada.name);
+        if (entrada.isDirectory()) {
+            achados.push(...listarArquivos(origem, relativo));
+        }
+        else if (entrada.isFile()) {
+            achados.push({ origem, relativo });
+        }
+    }
+    return achados;
+}
+/** Substitui os tres placeholders. Nao ha template engine aqui de proposito. */
+function renderizarArquivo(conteudo, valores) {
+    return conteudo
+        .replace(/\{\{ork_bin\}\}/g, valores.orkBin)
+        .replace(/\{\{catalogo\}\}/g, valores.catalogo)
+        .replace(/\{\{versao\}\}/g, valores.versao);
+}
+/**
+ * Instala o adaptador do host. Com `dryRun`, nada e escrito e o resultado diz o que seria.
+ *
+ * O retorno e tipado de proposito: o teste do bloco instala em diretorio temporario e confere
+ * o que foi escrito, em vez de conferir o que a funcao disse que escreveu.
+ */
+function instalarAdaptador(host, opcoes = {}) {
+    const def = exports.HOSTS[host];
+    const projeto = path.resolve(opcoes.projeto ?? process.cwd());
+    const catalogo = opcoes.catalogo ? path.resolve(opcoes.catalogo) : (0, catalogo_1.exigirCatalogo)(projeto);
+    const base = opcoes.dir
+        ? path.resolve(projeto, opcoes.dir)
+        : path.join(projeto, def.destinoPadrao);
+    const destino = def.subdir ? path.join(base, def.subdir) : base;
+    const orkBin = opcoes.orkBin ?? (0, util_1.noPath)('ork') ?? path.join(catalogo, 'core', 'dist', 'index.js');
+    const versao = opcoes.versao ?? '0.2.0';
+    const dirDoHost = path.join(catalogo, 'adapters', host);
+    if (!fs.existsSync(dirDoHost)) {
+        throw new Error(`adaptador do host ${host} nao existe em ${dirDoHost}`);
+    }
+    const fontes = listarArquivos(dirDoHost);
+    if (def.levaCatalogo) {
+        for (const skill of (0, catalogo_1.skillsDoCatalogo)(catalogo)) {
+            fontes.push({
+                origem: skill.caminho,
+                relativo: path.posix.join('skills', skill.bucket, skill.nome, 'SKILL.md'),
+            });
+        }
+        for (const ref of (0, catalogo_1.referenciasDoCatalogo)(catalogo)) {
+            fontes.push({ origem: ref, relativo: path.posix.join('references', path.basename(ref)) });
+        }
+    }
+    const arquivos = [];
+    for (const fonte of fontes) {
+        const ext = path.extname(fonte.origem);
+        const bruto = fs.readFileSync(fonte.origem);
+        const conteudo = RENDERIZAVEIS.has(ext)
+            ? Buffer.from(renderizarArquivo(bruto.toString('utf8'), { orkBin, catalogo, versao }), 'utf8')
+            : bruto;
+        const alvo = path.join(destino, fonte.relativo);
+        let estado = 'novo';
+        if (fs.existsSync(alvo)) {
+            estado = sha256(fs.readFileSync(alvo)) === sha256(conteudo) ? 'igual' : 'sobrescrito';
+        }
+        arquivos.push({
+            origem: fonte.origem,
+            destino: alvo,
+            relativo: fonte.relativo,
+            sha256: sha256(conteudo),
+            bytes: conteudo.length,
+            executavel: EXECUTAVEIS.has(ext),
+            estado,
+        });
+    }
+    const conflitos = arquivos.filter((a) => a.estado === 'sobrescrito');
+    const barrado = conflitos.length > 0 && opcoes.force !== true;
+    const resultado = {
+        host,
+        catalogo,
+        destino,
+        dryRun: opcoes.dryRun === true,
+        arquivos,
+        conflitos,
+        ok: !barrado,
+        orkBin,
+        pitfalls: def.pitfalls,
+    };
+    if (opcoes.dryRun === true || barrado)
+        return resultado;
+    for (const arquivo of arquivos) {
+        const ext = path.extname(arquivo.origem);
+        const bruto = fs.readFileSync(arquivo.origem);
+        const conteudo = RENDERIZAVEIS.has(ext)
+            ? Buffer.from(renderizarArquivo(bruto.toString('utf8'), { orkBin, catalogo, versao }), 'utf8')
+            : bruto;
+        fs.mkdirSync(path.dirname(arquivo.destino), { recursive: true });
+        fs.writeFileSync(arquivo.destino, conteudo);
+        if (arquivo.executavel)
+            fs.chmodSync(arquivo.destino, 0o755);
+    }
+    // O recibo: com ele da para saber, depois, se alguem editou a copia instalada em vez do
+    // catalogo. Sem ele a instalacao e um monte de arquivo sem procedencia.
+    fs.writeFileSync(path.join(destino, 'INSTALADO.json'), JSON.stringify({
+        contrato: 'ork.adapter-install/v1',
+        host,
+        versao,
+        catalogo,
+        orkBin,
+        instaladoEm: new Date().toISOString(),
+        arquivos: arquivos.map((a) => ({
+            arquivo: a.relativo,
+            origem: path.relative(catalogo, a.origem),
+            sha256: a.sha256,
+            bytes: a.bytes,
+        })),
+    }, null, 2) + '\n', 'utf8');
+    return resultado;
+}
+/** Texto de `ork adapter list`. */
+function tabelaDeHosts() {
+    const linhas = ['Adaptadores de host (Camada 1, o podio)', ''];
+    for (const host of exports.ORDEM_DOS_HOSTS) {
+        const def = exports.HOSTS[host];
+        linhas.push(`  ${host.padEnd(13)} ${def.descricao}`);
+        linhas.push(`  ${' '.repeat(13)} destino padrao: <projeto>/${def.destinoPadrao}${def.subdir ? '/' + def.subdir : ''}`);
+        linhas.push(`  ${' '.repeat(13)} catalogo de skills junto: ${def.levaCatalogo ? 'sim' : 'nao'}`);
+    }
+    linhas.push('');
+    linhas.push('Instale com: ork adapter install <host> [--dir DIR] [--dry-run] [--force]');
+    linhas.push('Zero regra de negocio no host: a #TAG vira `--mode` e a validacao e do nucleo.');
+    return linhas.join('\n');
+}
+/** Texto dos pitfalls de um host, impresso no fim de toda instalacao. */
+function textoDosPitfalls(host) {
+    const def = exports.HOSTS[host];
+    const linhas = [`Os 3 pitfalls de instalacao do ${host} (confira, nao suponha):`, ''];
+    def.pitfalls.forEach((p, i) => {
+        linhas.push(`  ${i + 1}. ${p.titulo}`);
+        linhas.push(`     ${p.detalhe}`);
+        linhas.push(`     prova: ${p.prova}`);
+        linhas.push('');
+    });
+    return linhas.join('\n').replace(/\n$/, '');
+}
+/** Texto de `ork adapter install`. */
+function textoDaInstalacao(r) {
+    const linhas = [];
+    linhas.push(r.dryRun
+        ? `Simulacao (--dry-run) da instalacao do adaptador ${r.host}: nada foi escrito.`
+        : r.ok
+            ? `Adaptador ${r.host} instalado.`
+            : `Instalacao do adaptador ${r.host} BARRADA: ha arquivo diferente no destino.`);
+    linhas.push(`  catalogo: ${r.catalogo}`);
+    linhas.push(`  destino:  ${r.destino}`);
+    linhas.push(`  ork:      ${r.orkBin}`);
+    linhas.push('');
+    const novos = r.arquivos.filter((a) => a.estado === 'novo').length;
+    const iguais = r.arquivos.filter((a) => a.estado === 'igual').length;
+    linhas.push(`  arquivos: ${r.arquivos.length} (${novos} novo(s), ${iguais} ja identico(s), ${r.conflitos.length} divergente(s))`);
+    for (const a of r.arquivos) {
+        const marca = a.estado === 'novo' ? '+' : a.estado === 'igual' ? '=' : '!';
+        linhas.push(`    ${marca} ${a.relativo}`);
+    }
+    if (!r.ok) {
+        linhas.push('');
+        linhas.push('  O destino tem arquivo diferente do catalogo. Ou a copia instalada foi editada');
+        linhas.push('  (e a correcao pertence ao catalogo), ou o catalogo andou. Para ressincronizar:');
+        linhas.push(`    ork adapter install ${r.host} --force`);
+    }
+    linhas.push('');
+    linhas.push(textoDosPitfalls(r.host));
+    return linhas.join('\n');
+}