passive-docs-index 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Passive Docs Index Contributors
+
+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,541 @@
+# Passive Docs Index (PDI)
+
+[![CI](https://img.shields.io/github/actions/workflow/status/syx-labs/passive-docs-index/ci.yml?branch=main&style=flat&label=CI)](https://github.com/syx-labs/passive-docs-index/actions/workflows/ci.yml)
+<!-- Coverage badge: configure COVERAGE_GIST_ID after creating the Gist -->
+<!-- [![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/syx-labs/GIST_ID/raw/coverage.json&label=Coverage)](https://github.com/syx-labs/passive-docs-index/actions/workflows/ci.yml) -->
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.x-f9f1e1.svg)](https://bun.sh/)
+
+> Elimine o ponto de decisão de busca de documentação para assistentes de código AI
+
+PDI cria um índice de documentação comprimido que está sempre disponível no seu `CLAUDE.md`, garantindo que assistentes de IA tenham acesso imediato à documentação de frameworks sem precisar decidir se devem buscá-la.
+
+## O Problema
+
+Estudos mostram que assistentes de IA têm uma taxa de falha de 56% ao acionar busca de documentação - frequentemente não consultam documentação quando deveriam. Isso leva a:
+
+- Código usando APIs deprecadas
+- Padrões incorretos do pré-treinamento
+- Erros de integração entre bibliotecas
+
+**Causa raiz:** O "ponto de decisão" - quando o agente precisa decidir "devo buscar documentação?", frequentemente escolhe não buscar.
+
+## A Solução
+
+PDI cria um **contexto passivo** - documentação que está sempre presente, eliminando o ponto de decisão. Em vez do AI decidir "devo consultar isso?", o índice de documentação relevante já está no contexto.
+
+| Abordagem | Taxa de Trigger | Custo de Tokens |
+|-----------|-----------------|-----------------|
+| Skills | 44% | Variável |
+| PDI Index | 100% | ~4KB constante |
+
+## Início Rápido
+
+```bash
+# Instalar globalmente
+bun add -g passive-docs-index
+# ou
+npm install -g passive-docs-index
+
+# Inicializar no seu projeto
+pdi init
+
+# Adicionar documentação de frameworks
+pdi add hono drizzle zod
+
+# Verificar status
+pdi status
+```
+
+## Como Funciona
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLAUDE.md                            │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │ [Conteúdo existente do usuário]                       │  │
+│  └───────────────────────────────────────────────────────┘  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │ <!-- pdi:begin -->                                    │  │
+│  │ [Índice Comprimido ~4KB]                              │  │
+│  │ <!-- pdi:end -->                                      │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    .claude-docs/                            │
+│  ├── frameworks/     (docs de dependências externas)        │
+│  ├── internal/       (padrões específicos do projeto)       │
+│  └── config.json     (configuração PDI)                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼ (fallback)
+┌─────────────────────────────────────────────────────────────┐
+│                    MCP Tools                                │
+│  Context7 → query-docs (quando docs locais insuficientes)   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Exemplo de Índice no CLAUDE.md
+
+```markdown
+<!-- pdi:begin - auto-generated by passive-docs-index, do not edit manually -->
+[Framework Docs]|root:.claude-docs/frameworks
+|CRITICAL:Prefer retrieval-led reasoning over pre-training-led reasoning
+|CRITICAL:Read the relevant .mdx files BEFORE writing code that uses these libraries
+|hono@4.x|api:{app.mdx,context.mdx,routing.mdx,middleware.mdx}|patterns:{error-handling.mdx,validation.mdx}
+|drizzle@0.44|schema:{tables.mdx,relations.mdx}|queries:{select.mdx,insert.mdx}
+|zod@4.x|basics:{schemas.mdx,validation.mdx}|advanced:{transforms.mdx}
+
+[Internal Patterns]|root:.claude-docs/internal
+|CRITICAL:Follow these project-specific patterns for consistency
+|database:{two-schema-pattern.mdx,feature-gating.mdx}
+|conventions:{esm-imports.mdx,path-aliases.mdx}
+<!-- pdi:end -->
+
+<!-- MCP Fallback: Context7 for expanded queries
+     hono=/honojs/hono, drizzle=/drizzle-team/drizzle-orm -->
+```
+
+## Comandos
+
+### `pdi init`
+
+Inicializa o PDI no seu projeto. Detecta dependências e cria a estrutura `.claude-docs/`.
+
+```bash
+pdi init                # Inicialização básica
+pdi init --force        # Sobrescrever configuração existente
+pdi init --no-detect    # Pular detecção de dependências
+pdi init --internal     # Também criar estrutura para docs internos
+```
+
+**Saída:**
+```
+✓ Created .claude-docs/
+✓ Created config.json
+✓ Updated .gitignore
+
+Detected dependencies:
+  ├── hono@4.9.12         → hono@4.x docs available
+  ├── drizzle-orm@0.44.6  → drizzle@0.44 docs available
+  └── zod@3.24.0          → zod@3.x docs available
+
+Run: pdi add hono drizzle zod
+```
+
+### `pdi add <frameworks...>`
+
+Adiciona documentação para frameworks específicos.
+
+```bash
+pdi add hono drizzle           # Adicionar múltiplos frameworks
+pdi add zod --version 3.x      # Especificar versão
+pdi add better-auth --force    # Sobrescrever docs existentes
+pdi add react --minimal        # Apenas docs essenciais
+pdi add vite --no-index        # Não atualizar índice no CLAUDE.md
+```
+
+**Saída:**
+```
+Fetching hono@4.x docs...
+  Source: Context7 (/honojs/hono)
+  ✓ api/app.mdx (2.1KB)
+  ✓ api/context.mdx (3.4KB)
+  ✓ api/routing.mdx (2.8KB)
+  Total: 7 files, 17KB
+
+✓ Updated index in CLAUDE.md
+```
+
+### `pdi sync`
+
+Sincroniza documentação com as dependências do `package.json`.
+
+```bash
+pdi sync              # Sincronização interativa
+pdi sync --yes        # Aceitar todas as mudanças automaticamente
+pdi sync --check      # Apenas verificar, sem modificar
+pdi sync --prune      # Remover docs de pacotes desinstalados
+```
+
+**Saída:**
+```
+Checking package.json...
+  ├── hono: 4.9.12 → docs at 4.x (OK)
+  ├── drizzle-orm: 0.44.6 → docs at 0.44 (OK)
+  └── better-auth: 1.3.27 → docs at 1.2.x (UPDATE AVAILABLE)
+
+Update better-auth docs? [y/N]
+```
+
+### `pdi status`
+
+Mostra o status atual do PDI.
+
+```bash
+pdi status
+```
+
+**Saída:**
+```
+PDI Status for my-project
+═════════════════════════
+
+Frameworks (3):
+  ├── hono@4.x      7 files  17KB  ✓ up-to-date
+  ├── drizzle@0.44  8 files  22KB  ✓ up-to-date
+  └── zod@4.x       4 files   9KB  ⚠ update available
+
+Internal (2 categories):
+  ├── database     3 files   8KB
+  └── conventions  2 files   4KB
+
+Index: 2.8KB / 4KB limit (70% used)
+Total docs: 60KB / 80KB limit (75% of limit)
+
+Last sync: 2026-02-02 16:00:00
+```
+
+### `pdi clean`
+
+Remove documentação órfã e otimiza o índice.
+
+```bash
+pdi clean              # Limpeza interativa
+pdi clean --yes        # Remover sem confirmar
+pdi clean --dry-run    # Mostrar o que seria removido
+```
+
+**Saída:**
+```
+Found orphan docs:
+  └── .claude-docs/frameworks/lodash/ (not in package.json)
+
+Remove orphan docs? [y/N] y
+✓ Removed lodash/ (4 files, 8KB)
+
+Index optimization:
+  Before: 4.2KB
+  After: 3.8KB
+  Saved: 0.4KB (10%)
+```
+
+### `pdi list`
+
+Lista templates de frameworks disponíveis.
+
+```bash
+pdi list                      # Listar todos
+pdi list --category backend   # Filtrar por categoria
+```
+
+### `pdi update [frameworks...]`
+
+Atualiza documentação para versões mais recentes.
+
+```bash
+pdi update              # Atualizar todos
+pdi update hono drizzle # Atualizar específicos
+```
+
+### `pdi generate internal`
+
+Analisa código e gera documentação de padrões internos.
+
+```bash
+pdi generate internal                 # Gerar todos
+pdi generate internal --category db   # Categoria específica
+pdi generate internal --dry-run       # Preview
+pdi generate internal --ai            # Usar AI para melhorar descrições
+```
+
+## Frameworks Suportados
+
+| Framework | Categoria | Versão | Library ID (Context7) |
+|-----------|-----------|--------|----------------------|
+| Hono | Backend | 4.x | /honojs/hono |
+| Drizzle ORM | Database | 0.44 | /drizzle-team/drizzle-orm |
+| Better Auth | Auth | 1.x | /better-auth/better-auth |
+| Zod | Validation | 4.x | /colinhacks/zod |
+| TanStack Query | Frontend | 5.x | /tanstack/query |
+| TanStack Router | Frontend | 1.x | /tanstack/router |
+| React | Frontend | 19.x | /facebook/react |
+| Vite | Build | 6.x | /vitejs/vite |
+| Vitest | Testing | 3.x | /vitest-dev/vitest |
+| Tailwind CSS | Styling | 4.x | /tailwindlabs/tailwindcss |
+
+## Estrutura do Projeto
+
+```
+your-project/
+├── .claude-docs/
+│   ├── config.json              # Configuração PDI
+│   ├── frameworks/              # Docs de dependências externas
+│   │   ├── hono/
+│   │   │   ├── api/
+│   │   │   │   ├── app.mdx
+│   │   │   │   ├── context.mdx
+│   │   │   │   ├── routing.mdx
+│   │   │   │   └── middleware.mdx
+│   │   │   └── patterns/
+│   │   │       ├── error-handling.mdx
+│   │   │       └── validation.mdx
+│   │   ├── drizzle/
+│   │   │   ├── schema/
+│   │   │   ├── queries/
+│   │   │   └── migrations/
+│   │   └── zod/
+│   │       ├── basics/
+│   │       └── advanced/
+│   └── internal/                # Padrões específicos do projeto
+│       ├── database/
+│       │   └── two-schema-pattern.mdx
+│       ├── conventions/
+│       │   └── esm-imports.mdx
+│       └── workflows/
+│           └── add-route.mdx
+├── CLAUDE.md                    # Contém o índice comprimido
+└── package.json
+```
+
+## Configuração
+
+O arquivo `config.json` controla o comportamento do PDI:
+
+```json
+{
+  "$schema": "https://pdi.dev/schema/config.json",
+  "version": "1.0.0",
+  "project": {
+    "name": "my-project",
+    "type": "backend"
+  },
+  "sync": {
+    "lastSync": "2026-02-02T16:00:00Z",
+    "autoSyncOnInstall": true
+  },
+  "frameworks": {
+    "hono": {
+      "version": "4.x",
+      "source": "context7",
+      "libraryId": "/honojs/hono",
+      "lastUpdate": "2026-02-01T00:00:00Z",
+      "files": 7
+    }
+  },
+  "internal": {
+    "enabled": true,
+    "categories": ["database", "conventions"],
+    "totalFiles": 5
+  },
+  "mcp": {
+    "fallbackEnabled": true,
+    "preferredProvider": "context7",
+    "libraryMappings": {
+      "hono": "/honojs/hono",
+      "drizzle": "/drizzle-team/drizzle-orm"
+    },
+    "cacheHours": 168
+  },
+  "limits": {
+    "maxIndexKb": 4,
+    "maxDocsKb": 80,
+    "maxFilesPerFramework": 20
+  }
+}
+```
+
+### Opções de Configuração
+
+| Campo | Descrição | Padrão |
+|-------|-----------|--------|
+| `project.type` | Tipo do projeto (backend/frontend/fullstack/library/cli) | auto-detectado |
+| `sync.autoSyncOnInstall` | Sincronizar automaticamente após `npm install` | `true` |
+| `mcp.fallbackEnabled` | Permitir fallback para MCP quando docs locais insuficientes | `true` |
+| `mcp.cacheHours` | Tempo de cache para queries MCP | `168` (1 semana) |
+| `limits.maxIndexKb` | Tamanho máximo do índice no CLAUDE.md | `4` |
+| `limits.maxDocsKb` | Tamanho máximo total dos docs | `80` |
+
+## Populando Documentação
+
+PDI cria arquivos de documentação placeholder. Para popular com conteúdo real:
+
+### Via Claude (Recomendado)
+
+Peça ao Claude para usar Context7 MCP para buscar e atualizar os docs:
+
+```
+Por favor, use Context7 para buscar documentação do Hono sobre routing
+e atualize o arquivo em .claude-docs/frameworks/hono/api/routing.mdx
+```
+
+### Manual
+
+Edite os arquivos `.mdx` diretamente com seu conteúdo preferido.
+
+### Formato do Arquivo .mdx
+
+```markdown
+---
+# Part of Passive Docs Index for hono@4.x
+# Source: Context7 (/honojs/hono)
+# Last updated: 2026-02-01
+# Category: api
+---
+
+# Routing
+
+## Overview
+
+Hono uses a simple and intuitive routing system...
+
+## Route Parameters
+
+```typescript
+app.get('/users/:id', (c) => {
+  const id = c.req.param('id');
+  return c.json({ id });
+});
+```
+
+## Common Patterns
+
+...
+```
+
+## Boas Práticas
+
+1. **Mantenha o índice abaixo de 4KB**: O índice deve ser escaneável rapidamente
+2. **Total de docs abaixo de 80KB**: Detalhe suficiente sem sobrecarregar o contexto
+3. **Alinhamento de versão**: Use `pdi sync` após `npm install` para manter docs atualizados
+4. **Padrões internos**: Documente convenções específicas do projeto em `.claude-docs/internal/`
+5. **Instruções CRITICAL**: Use para padrões que devem ser seguidos sem exceção
+
+## Integração com MCP
+
+PDI integra com Context7 MCP para fallback quando documentação local é insuficiente:
+
+```markdown
+<!-- MCP Fallback Protocol -->
+<!--
+When local docs in .claude-docs/ don't answer your question:
+1. Query Context7: mcp__plugin_context7_context7__query-docs
+2. Use the libraryId from config.json
+
+Library IDs:
+- hono: /honojs/hono
+- drizzle: /drizzle-team/drizzle-orm
+
+Only use MCP for:
+- Edge cases not covered in local docs
+- Very recent API changes
+- Integration patterns between libraries
+-->
+```
+
+## API Programática
+
+PDI também pode ser usado programaticamente:
+
+```typescript
+import {
+  readConfig,
+  writeConfig,
+  parseIndex,
+  generateIndex,
+  buildIndexSections,
+  updateClaudeMdIndex,
+  getTemplate,
+  hasTemplate,
+  listTemplates,
+} from 'passive-docs-index';
+
+// Ler configuração
+const config = await readConfig('/path/to/project');
+
+// Verificar se template existe
+if (hasTemplate('hono')) {
+  const template = getTemplate('hono');
+  console.log(template.structure);
+}
+
+// Construir e atualizar índice
+const sections = buildIndexSections(
+  '.claude-docs/frameworks',
+  '.claude-docs/internal',
+  frameworksData,
+  internalData
+);
+
+await updateClaudeMdIndex('/path/to/project', sections);
+```
+
+## Por Que Não Skills?
+
+Skills requerem que o AI tome uma decisão de trigger. Pesquisas mostram que este ponto de decisão tem alta taxa de falha. A abordagem passiva do PDI significa que o índice de documentação está sempre presente - nenhuma decisão necessária.
+
+### Comparação
+
+| Aspecto | Skills | PDI |
+|---------|--------|-----|
+| Taxa de Trigger | 44% | 100% |
+| Custo de Tokens | Variável | ~4KB constante |
+| Decisão Requerida | Sim | Não |
+| Sempre em Contexto | Não | Sim |
+
+## Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Fork o repositório
+2. Crie uma branch para sua feature (`git checkout -b feature/nova-feature`)
+3. Commit suas mudanças (`git commit -am 'Add nova feature'`)
+4. Push para a branch (`git push origin feature/nova-feature`)
+5. Abra um Pull Request
+
+### Adicionando Novos Templates
+
+Para adicionar suporte a um novo framework, edite `src/lib/templates.ts`:
+
+```typescript
+export const MEU_FRAMEWORK_TEMPLATE: FrameworkTemplate = {
+  name: 'meu-framework',
+  displayName: 'Meu Framework',
+  version: '1.x',
+  source: 'context7',
+  libraryId: '/org/meu-framework',
+  category: 'backend',
+  priority: 'P1',
+  description: 'Descrição do framework',
+  structure: {
+    basics: {
+      'getting-started.mdx': {
+        query: 'Query para Context7 sobre getting started',
+        topics: ['setup', 'installation'],
+      },
+    },
+  },
+};
+```
+
+## Roadmap
+
+- [x] CLI básico (init, add, status, sync, clean)
+- [x] Templates para 10 frameworks principais
+- [x] Integração com Context7 MCP
+- [ ] Comando `pdi generate internal` completo
+- [ ] Hook para `npm install` / `bun install`
+- [ ] Skills Claude (`/pdi-analyze`, `/pdi-generate`)
+- [ ] Plugin para VS Code
+- [ ] Dashboard web para visualização
+
+## Licença
+
+MIT © 2026
+
+---
+
+Feito com ❤️ para melhorar a experiência de desenvolvimento com AI assistants.

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * PDI CLI - Passive Docs Index
+ * A tool for managing passive documentation indices for AI coding assistants
+ */
+export {};
+//# 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":";AAEA;;;GAGG"}