@orkastery/cli 0.2.0

package/dist/orkmind.js

@@ -0,0 +1,487 @@
+"use strict";
+/**
+ * Cliente do OrkMind (bloco B6): a camada semantica como ADAPTADOR, nunca como dependencia.
+ *
+ * O `ork` continua sendo TypeScript deterministico e sem LLM. O OrkMind e Python, com
+ * Postgres + pgvector, e mora fora deste repositorio. A integracao aqui e de cliente:
+ * subprocess no CLI do OrkMind, entrada e saida em JSON, tolerancia a falha em todas as
+ * chamadas. Nada de embutir o Python, nada de reimplementar a ontologia.
+ *
+ * Tres regras que este arquivo existe para garantir:
+ *
+ *  1. DEGRADACAO HONESTA. Se o OrkMind nao responde, o regime efetivo vira `files` com
+ *     motivo TIPADO, e o ciclo segue. Memoria semantica melhora o produto; ela nao e
+ *     requisito dele.
+ *  2. ISOLAMENTO POR TENANT, SEM FALLBACK. A DSN vem do NOME de uma variavel de ambiente
+ *     declarada no manifesto (`memory.database_url_env`). Variavel nao declarada ou vazia
+ *     nao vira "usa a base padrao": vira degradacao. E o precedente do incidente
+ *     memory-orkmind, em que a memoria de um produto foi parar na base de outro.
+ *  3. GOVERNANCA. O `ork` grava com `source: agent` e NUNCA cria entrada `mandatory` nem
+ *     `rule`/`instruction` com prioridade `critical`. Regra critica so nasce de humano
+ *     autenticado. Aqui isso e checado antes de qualquer chamada, nao depois.
+ */
+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.DriverEmMemoria = exports.DriverCliOrkMind = exports.ESQUEMA_ORKMIND = exports.DIMENSOES = exports.COLECOES_DE_GOVERNANCA = exports.COLECOES_DO_ORK = void 0;
+exports.enderecoDeMemoria = enderecoDeMemoria;
+exports.lerEndereco = lerEndereco;
+exports.violacoesDeGovernanca = violacoesDeGovernanca;
+exports.casaTags = casaTags;
+exports.entradaDoJson = entradaDoJson;
+exports.configDoManifesto = configDoManifesto;
+exports.resolverRegime = resolverRegime;
+exports.filtrarPorTags = filtrarPorTags;
+exports.relativoDaRaiz = relativoDaRaiz;
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+/** As colecoes do OrkMind que o `ork` grava (visao unificada, tabela da secao 6). */
+exports.COLECOES_DO_ORK = [
+    'decision',
+    'handoff',
+    'rule',
+    'learning',
+    'roadmap',
+];
+/**
+ * Colecoes de governanca dura do OrkMind: entrada aqui vira REGRA do ecossistema.
+ * O agente pode gravar (o B6 grava as policies do manifesto), mas nunca como `mandatory`
+ * nem com prioridade `critical`: isso e privilegio de humano autenticado.
+ */
+exports.COLECOES_DE_GOVERNANCA = ['rule', 'instruction'];
+/** As 5 dimensoes semanticas usadas pelo `ork`. Busca por tag e EXATA nelas. */
+exports.DIMENSOES = [
+    'skill',
+    'agent',
+    'domain',
+    'project',
+    'situation',
+];
+/** Prefixo dos enderecos semanticos gravados nos ponteiros do handoff. */
+exports.ESQUEMA_ORKMIND = 'orkmind://';
+/** Monta o endereco semantico de uma entrada (`orkmind://<colecao>/<id>`). */
+function enderecoDeMemoria(colecao, id) {
+    return `${exports.ESQUEMA_ORKMIND}${colecao}/${id}`;
+}
+/** Le um endereco semantico de volta. Devolve null quando nao e um endereco do OrkMind. */
+function lerEndereco(endereco) {
+    if (!endereco.startsWith(exports.ESQUEMA_ORKMIND))
+        return null;
+    const resto = endereco.slice(exports.ESQUEMA_ORKMIND.length);
+    const corte = resto.indexOf('/');
+    if (corte <= 0 || corte === resto.length - 1)
+        return null;
+    return { colecao: resto.slice(0, corte), id: resto.slice(corte + 1) };
+}
+/**
+ * O que o `ork` recusa gravar, ANTES de chamar o OrkMind.
+ *
+ * Devolve a lista de violacoes; lista vazia quer dizer "pode gravar". Nao e defesa contra
+ * o OrkMind (ele tem a dele): e o `ork` recusando pedir o que ele nao tem direito de pedir.
+ */
+function violacoesDeGovernanca(entrada) {
+    const problemas = [];
+    if (!exports.COLECOES_DO_ORK.includes(entrada.collection)) {
+        problemas.push(`colecao "${entrada.collection}" fora do escopo do ork (${exports.COLECOES_DO_ORK.join(', ')})`);
+    }
+    if (exports.COLECOES_DE_GOVERNANCA.includes(entrada.collection) && entrada.priority === 'critical') {
+        problemas.push(`prioridade critical em "${entrada.collection}": regra critica so nasce de humano autenticado`);
+    }
+    if (entrada.content.trim() === '') {
+        problemas.push('conteudo vazio: entrada sem conteudo nao e memoria, e ruido');
+    }
+    for (const dimensao of Object.keys(entrada.tags)) {
+        if (!exports.DIMENSOES.includes(dimensao)) {
+            problemas.push(`dimensao de tag desconhecida: "${dimensao}" (validas: ${exports.DIMENSOES.join(', ')})`);
+        }
+    }
+    return problemas;
+}
+/**
+ * Casamento de tags DETERMINISTICO, o mesmo contrato do OrkMind:
+ *
+ *  - casa quando ha intersecao em TODA dimensao pedida (AND entre dimensoes, OR dentro);
+ *  - entrada `mandatory` casa com qualquer intersecao em UMA dimensao: ela sempre volta
+ *    quando o contexto toca o assunto dela.
+ *
+ * Nao ha similaridade nem ranking aqui: dois contextos iguais devolvem o mesmo conjunto.
+ */
+function casaTags(entrada, consulta) {
+    const dimensoes = Object.entries(consulta).filter(([, v]) => v.length > 0);
+    if (dimensoes.length === 0)
+        return true;
+    let algumaCasou = false;
+    let todasCasaram = true;
+    for (const [dimensao, valores] of dimensoes) {
+        const daEntrada = entrada.tags[dimensao] ?? [];
+        const casou = valores.some((v) => daEntrada.includes(v));
+        if (casou)
+            algumaCasou = true;
+        else
+            todasCasaram = false;
+    }
+    return todasCasaram || (entrada.mandatory && algumaCasou);
+}
+/** Normaliza uma entrada como o OrkMind a devolve (`orkmind export`). */
+function entradaDoJson(bruto) {
+    if (!bruto || typeof bruto !== 'object')
+        return null;
+    const o = bruto;
+    if (typeof o.id !== 'string' || typeof o.content !== 'string')
+        return null;
+    const tags = {};
+    if (o.tags && typeof o.tags === 'object' && !Array.isArray(o.tags)) {
+        for (const [k, v] of Object.entries(o.tags)) {
+            if (Array.isArray(v))
+                tags[k] = v.filter((x) => typeof x === 'string');
+        }
+    }
+    const prioridades = ['critical', 'high', 'medium', 'low'];
+    const prioridade = typeof o.priority === 'string' && prioridades.includes(o.priority)
+        ? o.priority
+        : 'medium';
+    return {
+        id: o.id,
+        collection: typeof o.collection === 'string' ? o.collection : '',
+        content: o.content,
+        tags,
+        priority: prioridade,
+        mandatory: o.mandatory === true,
+        scope: typeof o.scope === 'string' ? o.scope : 'project',
+        source: typeof o.source === 'string' ? o.source : 'agent',
+        metadata: o.metadata && typeof o.metadata === 'object' && !Array.isArray(o.metadata)
+            ? o.metadata
+            : {},
+        criadaEm: typeof o.created_at === 'string' ? o.created_at : '',
+    };
+}
+/**
+ * Driver real: subprocess no CLI do OrkMind.
+ *
+ * A DSN entra pelo ambiente do processo filho (`ORKMIND_DATABASE_URL`), nunca por
+ * argumento de linha de comando: argumento aparece em `ps` e no ledger de quem loga
+ * comando. E ela sai da variavel declarada no manifesto, sem nenhum outro candidato.
+ */
+class DriverCliOrkMind {
+    nome;
+    config;
+    saude = null;
+    constructor(config) {
+        this.config = config;
+        this.nome = `cli:${config.cli}`;
+    }
+    rodar(args) {
+        const r = (0, node_child_process_1.spawnSync)(this.config.cli, args, {
+            encoding: 'utf8',
+            timeout: this.config.timeoutMs,
+            // A base do tenant e a UNICA que entra aqui. Sem `ORKMIND_DATABASE_URL` herdada do
+            // ambiente do builder: isso e como memoria de um produto vaza para a base de outro.
+            env: { ...process.env, ORKMIND_DATABASE_URL: this.config.dsn },
+        });
+        return {
+            ok: r.status === 0,
+            stdout: (r.stdout ?? '').toString(),
+            stderr: (r.stderr ?? '').toString() || (r.error ? r.error.message : ''),
+        };
+    }
+    disponivel() {
+        if (this.saude)
+            return this.saude;
+        if (this.config.dsn.trim() === '') {
+            this.saude = { ok: false, detalhe: `${this.config.variavel} vazia no ambiente` };
+            return this.saude;
+        }
+        const r = this.rodar(['stats']);
+        this.saude = r.ok
+            ? { ok: true, detalhe: r.stdout.split('\n')[0]?.trim() || 'OrkMind respondeu' }
+            : { ok: false, detalhe: (r.stderr || r.stdout).trim().split('\n').slice(-1)[0] ?? 'sem detalhe' };
+        return this.saude;
+    }
+    adicionar(entrada) {
+        const args = [
+            'add',
+            '--collection',
+            entrada.collection,
+            '--content',
+            entrada.content,
+            '--tags',
+            JSON.stringify(entrada.tags),
+            '--priority',
+            entrada.priority,
+            '--scope',
+            'project',
+            // `source: agent` sempre: e assim que o OrkMind sabe que isto nao veio de humano.
+            '--source',
+            'agent',
+            // `--dedupe` torna a gravacao idempotente por content_hash: reprocessar um MASTER ou
+            // reexportar um handoff nao duplica memoria.
+            '--dedupe',
+            '--json',
+        ];
+        const r = this.rodar(args);
+        if (!r.ok) {
+            return {
+                ok: false,
+                id: null,
+                duplicada: false,
+                collection: entrada.collection,
+                detalhe: (r.stderr || r.stdout).trim().split('\n').slice(-1)[0] ?? 'falha sem detalhe',
+            };
+        }
+        const linha = r.stdout.trim().split('\n').filter((l) => l.trim() !== '').slice(-1)[0] ?? '';
+        try {
+            const json = JSON.parse(linha);
+            return {
+                ok: true,
+                id: json.entry_id ?? null,
+                duplicada: json.status === 'duplicate',
+                collection: entrada.collection,
+                detalhe: json.status ?? 'created',
+            };
+        }
+        catch {
+            return {
+                ok: false,
+                id: null,
+                duplicada: false,
+                collection: entrada.collection,
+                detalhe: `saida do OrkMind nao e JSON: ${linha.slice(0, 120)}`,
+            };
+        }
+    }
+    exportar(colecao) {
+        const r = this.rodar(['export', '--collection', colecao, '--output', '-']);
+        if (!r.ok)
+            return [];
+        try {
+            const dados = JSON.parse(r.stdout);
+            if (!Array.isArray(dados))
+                return [];
+            return dados.map(entradaDoJson).filter((e) => e !== null);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.DriverCliOrkMind = DriverCliOrkMind;
+/**
+ * Driver em memoria, usado pelos testes e por `--dry-run`.
+ *
+ * Ele implementa o MESMO contrato do driver real (governanca inclusa, ids estaveis), para
+ * que os criterios do B6 sejam provados de forma deterministica mesmo sem OrkMind no CI.
+ */
+class DriverEmMemoria {
+    nome = 'memoria';
+    entradas = [];
+    contador = 0;
+    /** Quando false, o driver se declara indisponivel: e o teste de degradacao. */
+    ligado = true;
+    constructor(entradas = []) {
+        for (const e of entradas)
+            this.entradas.push(e);
+        this.contador = this.entradas.length;
+    }
+    disponivel() {
+        return this.ligado
+            ? { ok: true, detalhe: `driver em memoria com ${this.entradas.length} entrada(s)` }
+            : { ok: false, detalhe: 'driver em memoria desligado' };
+    }
+    adicionar(entrada) {
+        if (!this.ligado) {
+            return {
+                ok: false,
+                id: null,
+                duplicada: false,
+                collection: entrada.collection,
+                detalhe: 'driver em memoria desligado',
+            };
+        }
+        const igual = this.entradas.find((e) => e.collection === entrada.collection && e.content === entrada.content);
+        if (igual) {
+            return {
+                ok: true,
+                id: igual.id,
+                duplicada: true,
+                collection: entrada.collection,
+                detalhe: 'duplicate',
+            };
+        }
+        this.contador += 1;
+        const nova = {
+            id: `mem-${String(this.contador).padStart(4, '0')}`,
+            collection: entrada.collection,
+            content: entrada.content,
+            tags: entrada.tags,
+            priority: entrada.priority,
+            mandatory: false,
+            scope: 'project',
+            source: 'agent',
+            metadata: entrada.metadata,
+            criadaEm: new Date().toISOString(),
+        };
+        this.entradas.push(nova);
+        return {
+            ok: true,
+            id: nova.id,
+            duplicada: false,
+            collection: entrada.collection,
+            detalhe: 'created',
+        };
+    }
+    exportar(colecao) {
+        if (!this.ligado)
+            return [];
+        return this.entradas.filter((e) => e.collection === colecao);
+    }
+    /** So para os testes: injeta uma entrada que o `ork` nunca gravaria (humano, mandatory). */
+    semear(entrada) {
+        this.entradas.push(entrada);
+        return entrada;
+    }
+    /** Tudo que existe no dublê, para as asserçoes dos testes. */
+    tudo() {
+        return [...this.entradas];
+    }
+}
+exports.DriverEmMemoria = DriverEmMemoria;
+/** Config de memoria efetiva a partir do manifesto, ja com o tenant resolvido. */
+function configDoManifesto(manifesto) {
+    const variavel = manifesto.memory.database_url_env ?? '';
+    return {
+        modo: manifesto.memory.mode,
+        cli: manifesto.memory.cli || 'orkmind',
+        variavel,
+        dsn: variavel ? (process.env[variavel] ?? '') : '',
+        timeoutMs: manifesto.memory.timeout_ms || 15000,
+        tenant: manifesto.memory.tenant || manifesto.project.name,
+    };
+}
+/** Texto acionavel para cada motivo de degradacao. */
+function correcaoDe(motivo, config) {
+    switch (motivo) {
+        case 'modo.files':
+            return 'para ligar a memoria semantica: memory.mode: orkmind + memory.database_url_env no manifesto';
+        case 'modo.desconhecido':
+            return 'memory.mode aceita files ou orkmind';
+        case 'dsn.nao-declarado':
+            return 'declare memory.database_url_env com o NOME da variavel de ambiente da base do tenant';
+        case 'dsn.env-ausente':
+            return `exporte ${config.variavel} com a DSN da base propria do tenant (o ork nao adivinha base)`;
+        case 'cli.ausente':
+            return `instale o OrkMind e garanta "${config.cli}" no PATH`;
+        case 'orkmind.indisponivel':
+            return 'suba o OrkMind (container do Postgres e a base do tenant) e rode ork memory status';
+    }
+}
+/**
+ * Resolve o regime EFETIVO de memoria.
+ *
+ * Este e o ponto unico em que "o manifesto pediu orkmind" vira "o orkmind esta valendo".
+ * Toda degradacao sai daqui com motivo tipado e correcao, e nenhuma delas quebra ciclo.
+ */
+function resolverRegime(manifesto, driver) {
+    const config = configDoManifesto(manifesto);
+    const base = {
+        pedido: config.modo,
+        variavel: config.variavel,
+        dsnPresente: config.dsn.trim() !== '',
+        cli: config.cli,
+        tenant: config.tenant,
+    };
+    const degradar = (motivo, detalhe) => ({
+        estado: {
+            ...base,
+            efetivo: 'files',
+            motivo,
+            detalhe,
+            correcao: correcaoDe(motivo, config),
+        },
+        driver: null,
+    });
+    if (config.modo === 'files') {
+        return degradar('modo.files', 'manifesto opera em regime files (fallback honesto do B1)');
+    }
+    if (config.modo !== 'orkmind') {
+        return degradar('modo.desconhecido', `memory.mode "${config.modo}" nao e um regime conhecido`);
+    }
+    // Isolamento por tenant: sem NOME de variavel declarado nao ha base, e nao ha palpite.
+    if (config.variavel === '') {
+        return degradar('dsn.nao-declarado', 'memory.database_url_env vazio: sem base declarada o ork nao conecta em base nenhuma');
+    }
+    if (config.dsn.trim() === '' && !driver) {
+        return degradar('dsn.env-ausente', `${config.variavel} nao esta no ambiente: o ork nao cai para outra DSN (precedente memory-orkmind)`);
+    }
+    const efetivoDriver = driver ?? new DriverCliOrkMind(config);
+    const saude = efetivoDriver.disponivel();
+    if (!saude.ok) {
+        const motivo = /não encontrad|not found|ENOENT|spawn/i.test(saude.detalhe)
+            ? 'cli.ausente'
+            : 'orkmind.indisponivel';
+        return degradar(motivo, `OrkMind nao respondeu: ${saude.detalhe}`);
+    }
+    return {
+        estado: {
+            ...base,
+            efetivo: 'orkmind',
+            motivo: null,
+            detalhe: `${efetivoDriver.nome} ativo na base declarada por ${config.variavel}: ${saude.detalhe}`,
+            correcao: '',
+        },
+        driver: efetivoDriver,
+    };
+}
+/** Consulta deterministica por tag sobre uma colecao ja exportada. */
+function filtrarPorTags(entradas, consulta) {
+    const casadas = entradas.filter((e) => casaTags(e, consulta.tags));
+    // Ordem estavel e independente do que o Postgres devolveu: mandatory primeiro, depois
+    // prioridade, depois data e id. Duas execucoes iguais montam o MESMO prompt.
+    const peso = { critical: 0, high: 1, medium: 2, low: 3 };
+    casadas.sort((a, b) => {
+        if (a.mandatory !== b.mandatory)
+            return a.mandatory ? -1 : 1;
+        const pa = peso[a.priority] ?? 9;
+        const pb = peso[b.priority] ?? 9;
+        if (pa !== pb)
+            return pa - pb;
+        if (a.criadaEm !== b.criadaEm)
+            return a.criadaEm.localeCompare(b.criadaEm);
+        return a.id.localeCompare(b.id);
+    });
+    return consulta.limite ? casadas.slice(0, consulta.limite) : casadas;
+}
+/** Caminho relativo a raiz, no formato usado pelos ponteiros do handoff. */
+function relativoDaRaiz(raiz, caminho) {
+    return path.relative(raiz, caminho).split(path.sep).join('/');
+}