Personal Docs Hover

Extensão local do Cursor/VS Code: no hover de uma keyword Ruby, mostra o Markdown de dump/docs/personal/.

Por que TypeScript + VS Code API

Estrutura

dump/docs/personal/
  _hover.json              → mapa keyword → arquivo.md
  progress-....md          → conteúdo do hover
  extensions/personal-docs-hover/
    package.json
    src/extension.ts
    out/extension.js       → gerado pelo compile

Instalação (Cursor)

1. Compilar (uma vez / após mudar o TS):

cd dump/docs/personal/extensions/personal-docs-hover
npm install
npm run compile

1. Command Palette → Developer: Install Extension from Location...
   Selecione a pasta dump/docs/personal/extensions/personal-docs-hover

2. Developer: Reload Window

3. Abra app/models/progress.rb ou app/controllers/procedures_controller.rb
   Passe o mouse em edited_progress, create_progress, assign_edited_progress, etc.

Scaffold incluso (v0.4)

A extensão traz a pasta interna scaffold/ com:

• README.md, INDEX.md, _TEMPLATE.md, _hover.json
• example-edited-progress.md (exemplo de hover + âncora)
• tasks/ e scripts/

Criar no workspace

Command Palette → Personal Docs Hover: Init Workspace Docs

• Cria dump/docs/personal/ (ou o path configurado)
• Não sobrescreve arquivos que já existem
• Se _hover.json não existir ao abrir um projeto Ruby, pergunta se quer criar

Distribuição (equipe + outras máquinas)

Opção A — arquivo .vsix (recomendada para começar)

1. Gerar o pacote (nesta pasta):

npm install
npm run compile
npx vsce package
# gera: personal-docs-hover-0.3.0.vsix

1. Instalar no Cursor/VS Code:

• Command Palette → Extensions: Install from VSIX...
• Selecione o .vsix
• Reload Window

1. Divulgar: envie o .vsix (Drive, Slack, e-mail) ou deixe em pasta compartilhada da equipe.

Cópia pronta para compartilhar (após vsce package):

dump/docs/personal/extensions/personal-docs-hover-0.3.0.vsix

Cada máquina/pessoa precisa ter também a pasta dump/docs/personal/ no workspace (notas + _hover.json). A extensão só exibe o hover; não leva as notas.

Opção B — Marketplace / Open VSX (público)

Para aparecer em “Extensions: Marketplace”:

1. Crie um publisher em https://marketplace.visualstudio.com/manage
2. npx vsce login <publisher>
3. npx vsce publish
4. (Cursor) também publique no Open VSX: https://open-vsx.org/

Use quando quiser instalação por nome, sem mandar arquivo.

Opção C — repositório Git interno

Suba só a pasta da extensão num repo; cada um clona e usa Install Extension from Location ou gera o .vsix no CI.

Layout do hover (v0.3)

• Cores no cabeçalho (keyword, título, author, status, âncora)
• Metadados lidos do .md: Author, Status, Tags, Descoberta
• Cabeçalhos ## / ### coloridos no corpo
• Truncamento + Abrir nota

No Markdown:

> Author: Emerson S. Mateus
> Status: estável
> Tags: progress, procedure
> Descoberta: 2026-07-30

Âncoras no Markdown (trecho)

Opcional. No .md mapeado:

<!-- hover: create_progress -->
## Quem chama
...
<!-- /hover: create_progress -->

• Hover em create_progress → só esse trecho
• Hover em keyword sem âncora no arquivo → arquivo inteiro
• Continua precisando da entrada no _hover.json

Mapa _hover.json

{
  "edited_progress": "progress-create-with-edited-progress.md",
  "create_progress": "progress-create-with-edited-progress.md"
}

• Keys = palavra sob o cursor (snake_case Ruby)
• Values = caminho relativo a dump/docs/personal/

Após editar o mapa: comando Personal Docs Hover: Reload Map
(ou só salvar o _hover.json — a extensão relê quando o mtime muda)

Settings (opcional)

{
  "personalDocsHover.docsPath": "dump/docs/personal",
  "personalDocsHover.mapFile": "_hover.json"
}

Desenvolvimento

npm run watch

Depois: Developer: Reload Window para pegar o out/ novo.