@promovaweb/specsfy 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Todas as mudanças relevantes do Specsfy CLI são registradas neste arquivo.
+
+## [Unreleased]
+
+## [0.7.0] - 2026-07-30
+
+- Migra o CLI e a TUI de Python para Node.js 22, com instalação global por
+  `@promovaweb/specsfy`.
+- Mantém as seis abas da TUI e adiciona execução do Pest com resumo e saída
+  rolável.
+- Corrige os atalhos de controle interpretados pelo `neo-blessed` e evita o
+  encerramento da TUI durante a atualização da saída dos testes.
+- Adiciona o fluxo de release com changelog, commit, tag anotada, GitHub
+  Actions, publicação npm e GitHub Release vinculados à mesma versão.
+- Atualiza o instalador, o catálogo de especialistas e a documentação do
+  usuário para os comandos do CLI em Node.js.
+
+- Autentica catálogo e verificação de tags em repositórios privados com
+  `GH_TOKEN`, `GITHUB_TOKEN` ou a sessão do GitHub CLI.
+- Torna o fingerprint do executável estável entre permissões equivalentes do
+  Git e ambientes locais/CI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Specsfy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# Specsfy CLI
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <picture>
+    <source srcset="../brand/logo/icon.svg" type="image/svg+xml">
+    <img src="../brand/logo/icon.png" alt="Logo do Specsfy" width="128">
+  </picture>
+</p>
+<!-- markdownlint-enable MD033 -->
+
+CLI e TUI para instalar e atualizar skills do Specsfy com segurança, detectar
+tecnologias e acompanhar em tempo real o progresso das specs de um projeto.
+
+## Pré-requisitos
+
+- Node.js 22.12 ou superior, com o npm disponível.
+- `skills`, do projeto
+  [`vercel-labs/skills`](https://github.com/vercel-labs/skills), ou `npx`
+  disponível para executá-lo sob demanda.
+- acesso autenticado ao repositório privado: execute `gh auth login` no uso
+  interativo ou defina `GH_TOKEN`/`GITHUB_TOKEN` na automação.
+
+## Download oficial
+
+O executável versionado é publicado em `get.specsfy.dev`. Ele reúne o código e
+as dependências JavaScript em um arquivo, mas continua usando o Node.js
+instalado na máquina. Coloque o arquivo em um diretório do seu `PATH` e preserve
+a permissão de execução.
+
+## Instalar com npm
+
+```bash
+npm install --global @promovaweb/specsfy
+specsfy --version
+```
+
+O npm instala o pacote publicado e disponibiliza o comando `specsfy`. Para
+atualizar a instalação global:
+
+```bash
+npm update --global @promovaweb/specsfy
+```
+
+O catálogo e a verificação de versões usam a API do GitHub. O CLI procura,
+nesta ordem, `GH_TOKEN`, `GITHUB_TOKEN` e a sessão retornada por
+`gh auth token`. As credenciais não são gravadas pelo Specsfy.
+
+Para instalar uma versão específica, informe a versão no próprio pacote:
+
+```bash
+npm install --global @promovaweb/specsfy@0.6.0
+```
+
+## Comandos
+
+```bash
+specsfy
+specsfy install --project .
+specsfy install --project . --detected
+specsfy install --project . \
+  --specialist specsfy-specialist-laravel \
+  --specialist specsfy-specialist-postgres
+specsfy skills list
+specsfy skills detect --project .
+specsfy skills add specsfy-specialist-laravel --project .
+specsfy skills remove specsfy-specialist-laravel --project .
+specsfy skills update --project .
+specsfy progress --project .
+specsfy progress --project . --json
+specsfy progress --project . --watch
+specsfy test --project .
+specsfy config show --project .
+specsfy config set --project . --watch-interval 0.5
+```
+
+Dependências declaradas pelo catálogo são resolvidas automaticamente. Por
+exemplo, instalar `specsfy-specialist-react-ui-components` também instala
+`specsfy-specialist-ui-design`, tanto pelo comando quanto pela TUI:
+
+```bash
+specsfy skills add specsfy-specialist-react-ui-components --project .
+```
+
+Sem subcomando, `specsfy` abre o dashboard TUI no diretório atual. A interface
+possui seis abas:
+
+- **Home**: totais de specs, tarefas, checklists e progresso global.
+- **Backlogs**: lista navegável à esquerda e preview Markdown formatado à
+  direita.
+- **Specs**: tabela detalhada com gates e progresso de cada especificação.
+  destaque uma linha e pressione `Espaço` para abrir a spec completa em um
+  modal Markdown rolável, retornando à listagem com `Esc`.
+- **Testes**: executa o Pest do projeto e separa o resultado entre as subabas
+  **Resumo** e **Testes**, mantendo a saída detalhada rolável.
+- **Skills**: catálogo tabular com plano, nome, categoria e estado, acompanhado
+  por um painel de detalhes e resumo das alterações pendentes.
+- **Sobre**: versão e finalidade do CLI.
+
+## Capturas de tela
+
+![Dashboard Home](../docs/user/assets/cli/cli-dash.png)
+
+![Backlogs](../docs/user/assets/cli/cli-backlogs.png)
+
+![Specs](../docs/user/assets/cli/cli-specs.png)
+
+![Skills](../docs/user/assets/cli/cli-skills.png)
+
+Alterações em `specs/inbox/*.md`, `specs/backlog/*.md`,
+`specs/specs/*/spec.md` e no `skills-lock.json` são detectadas
+automaticamente.
+
+Em projetos Laravel com Pest, `specsfy test --project .` detecta `artisan` e
+`pestphp/pest`, executa `php artisan test` a partir da raiz selecionada,
+transmite a saída e devolve o mesmo exit code. Na TUI, `Executar testes ^X`
+mostra status, runner, comando, duração e resumo em uma subaba. A outra exibe
+cada teste e falha. Relatórios Pest estruturados são convertidos em linhas
+legíveis com arquivo, linha e mensagem.
+
+O bootstrap instala as nove skills base, incluindo `specsfy-01-inbox` e
+`specsfy-update-spec` para pedidos surgidos depois da definição,
+`specsfy-setup`,
+`specsfy-documentator` e as três skills `specsfy-aux-*`, publica as regras em
+`.specsfy/Spec.md`, os templates `Inbox.md`, `Backlog.md`, `Spec.md`, `Tasks.md`,
+`Project.md`, `Stack.md`, `Rules.md` e `Database.md` em
+`.specsfy/templates/`, cria o diretório não gerenciado
+`.specsfy/templates/custom/`, publica um exemplo em
+`.specsfy/examples/Spec.md` e mescla blocos gerenciados em `AGENTS.md` e
+`CLAUDE.md`, preservando as instruções do usuário. Instalações repetidas são
+idempotentes. O lock registra fingerprints: versões intactas podem ser
+atualizadas, mas conteúdo gerenciado customizado localmente só é substituído ou
+removido com `--force`. Arquivos em `.specsfy/templates/custom/` sempre têm
+precedência sobre os homônimos gerenciados e nunca são alterados, nem com
+`--force`.
+
+A materialização das skills é delegada ao comando oficial:
+
+```bash
+npx skills add <repositorio> \
+  --skill <nome> \
+  --agent universal \
+  --copy \
+  -y \
+  --full-depth
+```
+
+O `skills-lock.json` gerado por essa ferramenta registra a proveniência e é a
+fonte usada pela aba Skills para marcar os checkboxes instalados. Quando ainda
+não existe em um projeto consumidor, o CLI cria o lock vazio compatível:
+
+```json
+{
+  "version": 1,
+  "skills": {}
+}
+```
+
+O gerenciador lista exclusivamente `specsfy-setup`, `specsfy-documentator` e
+skills do catálogo base, `specsfy-aux-*` e `specsfy-specialist-*`. Skills externas
+presentes no mesmo lock não aparecem na interface e nunca são removidas ou
+alteradas. O `.specsfy/skills-lock.json`
+mantém os fingerprints usados pelo Specsfy para impedir que uma atualização
+descarte alterações locais.
+
+Na aba Skills, o botão `Atualizar ^R` baixa as origens atuais e atualiza de uma
+vez todas as skills Specsfy instaladas. O comando equivalente é
+`specsfy skills update --project .`. Customizações locais continuam protegidas e
+só podem ser substituídas explicitamente com `--force` no comando.
+
+## Atualização do CLI gerenciada pelo npm
+
+Ao abrir `specsfy` ou `specsfy tui` em um terminal interativo, o CLI consulta
+as tags semânticas estáveis do monorepo. A consulta é limitada pelo cache
+global `~/.specsfy/cli.json`, cujo intervalo padrão é de 24 horas. Falha de rede
+ou do GitHub nunca impede a abertura do dashboard.
+
+Quando existe versão mais recente, o CLI mostra as versões atual e disponível e
+pergunta antes de atualizar. Uma resposta negativa abre a aplicação normalmente.
+Uma resposta positiva delega a atualização ao npm, que instala a versão mais
+recente de `@promovaweb/specsfy` no escopo global. O processo então fecha. Abra
+`specsfy` novamente para iniciar a versão instalada.
+
+O arquivo global usa permissão `0600`, preserva chaves desconhecidas e separa:
+
+- `settings.check_updates_on_startup`.
+- `settings.check_interval_seconds`.
+- `cache.last_checked_at`, tag, versão, commit, ETag e eventual erro recente.
+
+Para publicar uma versão atualizável a partir do workspace de desenvolvimento,
+use a skill local `$specsfy-release-cli`. Ela promove as notas confirmadas para
+o [`CHANGELOG.md`](CHANGELOG.md), atualiza as versões do pacote e o lock,
+reconstrói os artefatos versionados, cria a tag anotada `v<versão>` no mesmo
+commit e usa exatamente a seção promovida como corpo do GitHub Release. O CI
+valida o build e a correspondência da tag.
+
+Novas specs usam `specs/specs/<NNNN>-<slug>/spec.md`. Capturas imediatas ficam
+em `specs/inbox/<data-hora>-<slug>.md` e itens refináveis em
+`specs/backlog/<NNNN>-<slug>.md`. O dashboard mantém leitura do layout
+legado. A skill de especificação renderiza cada arquivo novo a partir do
+template instalado. O CLI recusa instalação na raiz do monorepo oficial.
+
+## Executável versionado
+
+O executável empacotado fica em `bin/specsfy`, contém as dependências do CLI e
+requer apenas o Node.js compatível. Reconstrua-o depois de qualquer alteração
+neste módulo:
+
+```bash
+npm run build:executable
+```
+
+`bin/specsfy.build.json` registra o fingerprint dos inputs. A suíte de testes
+falha quando o artefato não corresponde ao estado atual.
+
+O pacote publicado no npm usa `@promovaweb/specsfy`. A tag estável dispara o
+job de publicação depois que tipos, testes, build, instalação local e
+executável versionado passam no CI. O job inclui proveniência quando o
+repositório estiver público; enquanto ele permanecer privado, publica com o
+token do registro e sem essa atestação.
+
+## Atalhos da TUI
+
+- `Ctrl+Q`: sair.
+- `Ctrl+U`: atualizar.
+- `Ctrl+D`: detectar recomendações.
+- `Ctrl+B`: selecionar todas as skills do framework.
+- `Ctrl+E`: alternar o plano da skill destacada.
+- `Ctrl+V` / `Ctrl+L`: marcar ou limpar os itens visíveis.
+- `Ctrl+A`: aplicar.
+- `Ctrl+R`: atualizar todas as skills Specsfy instaladas.
+- `Ctrl+T`, `Ctrl+N`, `Ctrl+C`: filtros Todas, Instaladas e Recomendadas.
+- `Ctrl+H`, `Ctrl+G`, `Ctrl+S`, `Ctrl+K`, `Ctrl+O`: Home, Backlogs, Specs,
+  Skills e Sobre.
+- `Ctrl+J`: abre Testes.
+- `Ctrl+X`: executa os testes do projeto.
+- `Espaço`: abre a spec destacada ou alterna a skill destacada, conforme a aba.
+- `Esc`: fecha o modal da spec, limpa a busca de Skills ou volta para Home.
+
+Cada botão mostra seu atalho no próprio rótulo. `Tab` e `Shift+Tab` percorrem
+os controles e as setas navegam as tabelas. Na aba Skills, `Enter` ou `Espaço`
+alternam o plano entre instalar, manter, remover e ignorar. Na aba Specs, abrem
+o modal da linha destacada. O campo de projeto entra em edição com `Enter` ou
+com um clique e atualiza o dashboard depois da confirmação. `Esc` retorna, e o
+mouse opera abas, linhas e botões. Nada é instalado ou removido antes de
+`Aplicar`.
+
+A documentação completa está em [`docs/`](../docs/).

package/bin/specsfy.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+void import("../dist/main.js");

package/dist/backlog.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Leitura dos itens de backlog de um projeto consumidor.
+ */
+/** Projeção de um arquivo em `specs/backlog/`. */
+export interface BacklogItem {
+    slug: string;
+    title: string;
+    identifier: string;
+    status: string;
+    path: string;
+    content: string;
+}
+/** Lê todos os backlogs do projeto em ordem estável. */
+export declare function scanBacklogs(project: string): Promise<BacklogItem[]>;
+/** Calcula o fingerprint dos caminhos e conteúdos de backlog. */
+export declare function backlogsFingerprint(project: string): Promise<string>;
+//# sourceMappingURL=backlog.d.ts.map

package/dist/backlog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.d.ts","sourceRoot":"","sources":["../src/backlog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wDAAwD;AACxD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAG1E;AAED,iEAAiE;AACjE,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1E"}

package/dist/backlog.js

@@ -0,0 +1,73 @@
+/**
+ * Leitura dos itens de backlog de um projeto consumidor.
+ */
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+import { isFile, resolvePath } from "./filesystem.js";
+const FIELD = /^\*\*([^*]+)\*\*:\s*(.+?)\s*$/;
+const TABLE_FIELD = /^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*$/;
+/** Lê todos os backlogs do projeto em ordem estável. */
+export async function scanBacklogs(project) {
+    const root = resolvePath(project);
+    return Promise.all((await backlogPaths(root)).map(parseBacklog));
+}
+/** Calcula o fingerprint dos caminhos e conteúdos de backlog. */
+export async function backlogsFingerprint(project) {
+    const root = resolvePath(project);
+    const digest = createHash("sha256");
+    for (const path of await backlogPaths(root)) {
+        digest.update(relative(root, path));
+        digest.update("\0");
+        try {
+            digest.update(await readFile(path));
+        }
+        catch {
+            continue;
+        }
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+async function backlogPaths(root) {
+    const directory = join(root, "specs", "backlog");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return [];
+    }
+    const paths = names
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => join(directory, name));
+    const checks = await Promise.all(paths.map(isFile));
+    return paths.filter((_, index) => checks[index]).sort();
+}
+async function parseBacklog(path) {
+    const content = await readFile(path, "utf8");
+    const slug = basename(path, ".md");
+    let title = slug;
+    const fields = new Map();
+    for (const line of content.split(/\r?\n/u)) {
+        if (line.startsWith("# ") && title === slug) {
+            title = line.slice(2).trim();
+            if (title.toLowerCase().startsWith("backlog:")) {
+                title = title.split(":", 2)[1]?.trim() ?? title;
+            }
+        }
+        const match = FIELD.exec(line) ?? TABLE_FIELD.exec(line);
+        if (match?.[1] && match[2]) {
+            fields.set(match[1].trim().toLowerCase(), match[2].trim());
+        }
+    }
+    return {
+        slug,
+        title,
+        identifier: fields.get("id") ?? slug,
+        status: fields.get("status") ?? "Unknown",
+        path,
+        content,
+    };
+}
+//# sourceMappingURL=backlog.js.map

package/dist/backlog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.js","sourceRoot":"","sources":["../src/backlog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,KAAK,GAAG,+BAA+B,CAAC;AAC9C,MAAM,WAAW,GAAG,yCAAyC,CAAC;AAY9D,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAe;IAChD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,IAAY;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACjD,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAG,KAAK;SAChB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC5C,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC;YAClD,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI;QACJ,KAAK;QACL,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI;QACpC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,SAAS;QACzC,IAAI;QACJ,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/catalog.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Catálogo de especialistas e detecção de tecnologias do projeto.
+ */
+export declare const DEFAULT_CATALOG_URL = "https://api.github.com/repos/promovaweb/specsfy/contents/specialists/catalog.json?ref=main";
+/** Entrada normalizada do catálogo de especialistas. */
+export interface CatalogEntryValue {
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    files: string[];
+    dependencies: string[];
+    requires: string[];
+}
+/** Catálogo validado com resolução de dependências entre especialistas. */
+export declare class Catalog {
+    #private;
+    readonly entries: CatalogEntryValue[];
+    constructor(entries: CatalogEntryValue[]);
+    /** Constrói o catálogo a partir do schema JSON público. */
+    static fromPayload(payload: unknown): Catalog;
+    /** Lê o catálogo de um arquivo local. */
+    static fromPath(path: string): Promise<Catalog>;
+    /** Obtém o catálogo remoto ou usa o override de ambiente. */
+    static fetch(url?: string): Promise<Catalog>;
+    /** Exige uma skill existente com o namespace de especialistas. */
+    require(name: string): CatalogEntryValue;
+    /** Resolve requisitos em ordem topológica e rejeita ciclos. */
+    resolve(names: string[]): CatalogEntryValue[];
+    /** Detecta entradas por arquivos marcadores e dependências declaradas. */
+    detect(project: string): Promise<CatalogEntryValue[]>;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,eAAO,MAAM,mBAAmB,+FAC8D,CAAC;AAE/F,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAcD,2EAA2E;AAC3E,qBAAa,OAAO;;IAClB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAGtC,YAAY,OAAO,EAAE,iBAAiB,EAAE,EAKvC;IAED,2DAA2D;IAC3D,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAqB5C;IAED,yCAAyC;IACzC,OAAa,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpD;IAED,6DAA6D;IAC7D,OAAa,KAAK,CAAC,GAAG,SAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB9D;IAED,kEAAkE;IAClE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CASvC;IAED,+DAA+D;IAC/D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAkB5C;IAED,0EAA0E;IACpE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAgB1D;CACF"}

package/dist/catalog.js

@@ -0,0 +1,135 @@
+/**
+ * Catálogo de especialistas e detecção de tecnologias do projeto.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { apiHeaders } from "./github.js";
+import { isFile, pathExists, resolvePath } from "./filesystem.js";
+export const DEFAULT_CATALOG_URL = "https://api.github.com/repos/promovaweb/specsfy/contents/specialists/catalog.json?ref=main";
+/** Catálogo validado com resolução de dependências entre especialistas. */
+export class Catalog {
+    entries;
+    #byName;
+    constructor(entries) {
+        this.entries = [...entries].sort((left, right) => left.name.localeCompare(right.name));
+        this.#byName = new Map(entries.map((entry) => [entry.name, entry]));
+    }
+    /** Constrói o catálogo a partir do schema JSON público. */
+    static fromPayload(payload) {
+        if (!payload ||
+            typeof payload !== "object" ||
+            payload.schema_version !== 1 ||
+            !Array.isArray(payload.skills)) {
+            throw new Error("versão de catálogo não suportada");
+        }
+        const source = payload;
+        return new Catalog(source.skills.map((value) => ({
+            name: value.name,
+            description: value.description,
+            category: value.category,
+            tags: value.tags ?? [],
+            files: value.detect?.files ?? [],
+            dependencies: value.detect?.dependencies ?? [],
+            requires: value.requires ?? [],
+        })));
+    }
+    /** Lê o catálogo de um arquivo local. */
+    static async fromPath(path) {
+        return Catalog.fromPayload(JSON.parse(await readFile(resolvePath(path), "utf8")));
+    }
+    /** Obtém o catálogo remoto ou usa o override de ambiente. */
+    static async fetch(url = DEFAULT_CATALOG_URL) {
+        const override = process.env.SPECSFY_SPECIALISTS_CATALOG;
+        if (override)
+            return Catalog.fromPath(override);
+        const response = await fetch(url, {
+            headers: await apiHeaders("specsfy-cli", "application/vnd.github.raw+json"),
+            signal: AbortSignal.timeout(20_000),
+        });
+        if (!response.ok) {
+            if ([401, 403, 404].includes(response.status)) {
+                throw new Error("catálogo de especialistas indisponível; autentique o GitHub " +
+                    "com `gh auth login` ou defina GH_TOKEN");
+            }
+            throw new Error(`falha ao consultar catálogo: HTTP ${response.status}`);
+        }
+        return Catalog.fromPayload((await response.json()));
+    }
+    /** Exige uma skill existente com o namespace de especialistas. */
+    require(name) {
+        if (!name.startsWith("specsfy-specialist-")) {
+            throw new Error("a skill especialista deve usar o prefixo specsfy-specialist-");
+        }
+        const entry = this.#byName.get(name);
+        if (!entry)
+            throw new Error(`skill não encontrada no catálogo: ${name}`);
+        return entry;
+    }
+    /** Resolve requisitos em ordem topológica e rejeita ciclos. */
+    resolve(names) {
+        const resolved = [];
+        const completed = new Set();
+        const active = new Set();
+        const visit = (name) => {
+            if (completed.has(name))
+                return;
+            if (active.has(name)) {
+                throw new Error(`dependência circular entre especialistas: ${name}`);
+            }
+            const entry = this.require(name);
+            active.add(name);
+            for (const required of entry.requires)
+                visit(required);
+            active.delete(name);
+            completed.add(name);
+            resolved.push(entry);
+        };
+        for (const name of names)
+            visit(name);
+        return resolved;
+    }
+    /** Detecta entradas por arquivos marcadores e dependências declaradas. */
+    async detect(project) {
+        const root = resolvePath(project);
+        const dependencies = await readDependencies(root);
+        const detected = [];
+        for (const entry of this.entries) {
+            const matches = await Promise.all(entry.files.map((marker) => pathExists(join(root, marker))));
+            if (matches.some(Boolean) ||
+                entry.dependencies.some((dependency) => dependencies.has(dependency))) {
+                detected.push(entry);
+            }
+        }
+        return detected;
+    }
+}
+async function readDependencies(project) {
+    const dependencies = new Set();
+    for (const filename of ["package.json", "composer.json"]) {
+        const path = join(project, filename);
+        if (!(await isFile(path)))
+            continue;
+        let payload;
+        try {
+            payload = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        for (const key of [
+            "dependencies",
+            "devDependencies",
+            "require",
+            "require-dev",
+            "peerDependencies",
+        ]) {
+            const value = payload[key];
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                for (const dependency of Object.keys(value))
+                    dependencies.add(dependency);
+            }
+        }
+    }
+    return dependencies;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entrada pública do Specsfy CLI.
+ *
+ * Define a gramática de comandos e coordena módulos de domínio sem incorporar
+ * regras de instalação, catálogo ou progresso.
+ */
+import { Command } from "commander";
+/** Constrói o parser público sem executar efeitos. */
+export declare function buildProgram(): Command;
+/** Executa o CLI e converte falhas conhecidas em exit code previsível. */
+export declare function runCli(argv?: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAA0B,MAAM,WAAW,CAAC;AAoB5D,sDAAsD;AACtD,wBAAgB,YAAY,IAAI,OAAO,CAkKtC;AAED,0EAA0E;AAC1E,wBAAsB,MAAM,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBjE"}