DeepWorkPlan Vim

O DeepWorkPlan Vim é o editor de terminal do Deep Work Plan: uma configuração do Neovim para pessoas, e para agentes de programação, que trabalham num terminal. Os seus planos, a sua documentação e um índice de todos os comandos ficam a uma tecla de distância.

É um produto à parte, oferecido como o addon opcional vim do Deep Work Plan v7 (v7.0.0). O Deep Work Plan funciona com qualquer editor ou com nenhum, e o editor não exige o Deep Work Plan: acrescenta-o a uma máquina por si só, e funciona como editor exista ou não um plano. Esta página descreve a versão v0.5.0.

Porquê um editor de terminal para o Deep Work Plan

Um Deep Work Plan é uma pasta de Markdown em .dwp/plans/: um objetivo, tarefas atómicas, validation gates e um registo contínuo. As pessoas revêem-no, os agentes executam-no, e uns e outros fazem-no muitas vezes a partir de um terminal. Um editor pensado para esse trabalho mantém três coisas por perto: o plano, a documentação à sua volta e as teclas que o levam de um ao outro.

O DeepWorkPlan Vim é esse editor. É uma configuração cuidada do Neovim — servidores de linguagem, completamento, linting, formatação, pesquisa difusa, uma árvore de ficheiros e temas de cor selecionados, com carregamento diferido — mais as poucas superfícies que o tornam o editor do Deep Work Plan.

A visita guiada: um índice de comandos que não se desatualiza

Prima SPC h h (o Espaço é a tecla líder), ou execute :DwpCommands, e o editor lista todos os atalhos que tem, com uma descrição de uma linha. A lista é gerada a partir dos atalhos ativos, por isso um atalho definido em qualquer lado aparece no índice sem ser registado, e o índice não pode ficar desatualizado.

É toda a visita: abra o nvim e prima Espaço, h, h.

O que obtém

Cinco funcionalidades, cada uma a uma tecla de distância.

Planos sem sair do editor

SPC P, :DwpPlans ou um clique no segmento da linha de estado abre a barra lateral de planos. Abrange cada pasta .dwp/plans/ do diretório atual e do diretório de configuração do Neovim, e agrupa os planos começando pelos que pedem mais atenção. No editor, as etiquetas são Working, Needs attention, Ready, Not started e Done. Cada plano mostra uma barra de progresso.

Prima Enter num plano para abrir o leitor: o objetivo numa frase, o estado e o progresso, a lista de tarefas com a tarefa atual assinalada e saltos em linguagem simples para os ficheiros do próprio plano. A linha de estado mostra o plano ativo em direto e o ecrã inicial lista os três primeiros. Estas superfícies explicam os planos; nunca escrevem em .dwp/.

Para ler no local os ficheiros Markdown de um plano, SPC m p pré-visualiza o buffer atual no navegador e SPC m r renderiza-o dentro do buffer. Ambos funcionam apenas em buffers de Markdown.

Instalação

A instalação são três comandos: descarregue o script, verifique-o com o SHA-256 do ficheiro que este site serve e depois execute-o. O instalador fixa a sua própria versão, pelo que instala exatamente v0.5.0, a versão que esta página descreve, a menos que escolha outra versão.

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
echo "4890c140528d6b8d19b6bbc4102051e0b9dce2e26f43a693bdeab2e1cd8e196b  install.sh" | shasum -a 256 -c && \
bash install.sh

Por ordem, o instalador:

1. Verifica o seu sistema operativo e o gestor de pacotes, e instala o git, o curl e um interpretador de Lua se faltar algum (nenhum com --skip-packages).
2. Resolve a versão: a sua própria versão, ou a que --version pedir.
3. Com --nvim X.Y.Z, instala essa versão do Neovim em ~/.local/opt, verificada com o SHA-256 que o Neovim publica.
4. Pergunta antes de mexer numa configuração do Neovim existente. Sem terminal, para e não altera nada, a menos que --yes lhe indique que afaste essa configuração.
5. Clona o repositório para ~/.config/nvim, ou atualiza-o se já lá estiver.
6. Executa o próprio lua install.lua do repositório.
7. Instala os plugins sem interface e verifica-os, pelo que não há passo de sair e voltar a abrir. Com --strict, uma instalação de plugins falhada ou incompleta é um erro.

O script aqui servido é uma cópia idêntica byte a byte do install.sh na etiqueta v0.5.0. A sua soma de verificação é servida ao lado, em https://deepworkplan.com/vim/install.sh.sha256, pelo que pode verificar a transferência com shasum -a 256 -c install.sh.sha256 (no Linux, sha256sum -c install.sh.sha256). Para uma verificação a partir de uma segunda origem, compare-a com a linha de install.sh do SHA256SUMS na versão publicada no GitHub. Execute bash install.sh --help para listar todas as opções.

Escolher uma versão

Por predefinição, o instalador instala a sua própria versão, v0.5.0. Para escolher outra, defina DWP_VIM_VERSION ou passe --version: ambos fazem o mesmo, por isso use o que se ler melhor; uma opção prevalece sobre o ambiente. Cada um aceita:

Depois da transferência e da verificação da soma acima:

# exact version
DWP_VIM_VERSION=0.5.0 bash install.sh
bash install.sh --version 0.5.0

# minimum floor: the newest stable release at or above 0.4.2
DWP_VIM_VERSION='>=0.4.2' bash install.sh

# latest stable release
bash install.sh --version latest

Coloque o mínimo entre aspas, para que a shell não interprete > como um redirecionamento. As versões resolvem-se apenas para etiquetas de versões estáveis. Para um ramo ou um commit, defina antes DWP_VIM_REF (DWP_VIM_REF=main segue o main); uma versão e uma referência que não coincidem são um erro.

Contentores e CI

Numa imagem ou num job de CI, onde não há terminal e muitas vezes não há root, descarregue e verifique o script e depois execute-o num só passo com opções que tornam o resultado reprodutível:

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
sha256sum -c install.sh.sha256 && \
bash install.sh --version 0.5.0 --nvim 0.12.5 --skip-packages --strict

• --version 0.5.0 fixa a versão do editor.
• --nvim 0.12.5 instala essa versão do Neovim em ~/.local/opt/nvim-v0.12.5, ligada como ~/.local/bin/nvim e verificada com o SHA-256 que o Neovim publica (Linux e macOS).
• --skip-packages não instala nenhum pacote do sistema: a imagem já tem de fornecer o git, o curl e o Lua.
• --strict termina com um código diferente de zero quando a instalação de plugins sem interface falha ou deixa plugins em falta.

Cada opção tem uma variável de ambiente equivalente (DWP_VIM_VERSION, DWP_VIM_NVIM, DWP_VIM_SKIP_PACKAGES=1, DWP_VIM_STRICT=1). Acrescente --yes apenas quando a imagem já possa conter uma configuração do Neovim que deva ser afastada.

Requisitos e plataformas

• Neovim 0.12 ou mais recente. Instale-o você mesmo, ou deixe o instalador acrescentar uma versão verificada com --nvim X.Y.Z (Linux e macOS).
• Lua: lua, lua5.4 ou luajit. O instalador acrescenta um se faltar.
• macOS, Linux e WSL executam o instalador. O Windows tem um caminho manual documentado no README do repositório: instale o Neovim com o winget, clone a etiqueta v0.5.0 para %LOCALAPPDATA%\nvim e execute lua install.lua a partir do Git Bash.
• Licença GPL-3.0: livre de usar, estudar e modificar.

Atualizar, fixar versão e desinstalar

Para atualizar, execute o instalador de uma versão mais recente, ou execute bash install.sh --version latest. Executá-lo de novo move uma instalação existente do DeepWorkPlan Vim para a versão escolhida, mantém os seus ramos e nunca repõe as alterações locais: quando alterações ou commits locais se perderiam, para e não altera nada.

Para fixar uma versão, use --version (consulte Escolher uma versão); para um ramo ou um commit, defina DWP_VIM_REF. Prefira uma versão publicada: as versões anteriores a v0.4.0 não incluem os gestos, o navegador de planos, o visualizador de Markdown nem este instalador.

# pin a specific release, here the previous one
curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
shasum -a 256 -c install.sh.sha256 && \
bash install.sh --version 0.4.2

Para desinstalar, execute lua delete.lua a partir do diretório de configuração. Remove a configuração, os plugins, os dados do Mason, a cache e o estado, e a cópia da fonte que o instalador fez, e deixa intactos o binário do Neovim e os pacotes do sistema.

cd ~/.config/nvim && lua delete.lua

Perguntas

Vai substituir a minha configuração do Neovim?

Não, não sem a sua aprovação. Quando encontra uma configuração que não é o DeepWorkPlan Vim, uma execução interativa pergunta antes de a mover para ~/.config/previous-deepworkplan-vim. Sem terminal, para e não altera nada, a menos que passe --yes para a afastar sem intervenção. Quando esse caminho de cópia já existe, para sempre e não altera nada.

Funciona no Windows?

O instalador não é executado no Windows. Use o caminho manual do README do repositório, ou execute o instalador dentro do WSL.

Preciso do Deep Work Plan para o usar?

Não. É primeiro um editor. Não instala nem exige a skill do Deep Work Plan; o navegador de planos simplesmente não tem nada para listar até existir uma pasta .dwp/plans/.

Como o usa o addon vim da v7?

O Deep Work Plan v7 oferece o editor como o addon opcional vim durante o onboarding. O addon deteta uma instalação existente apenas em modo de leitura, através do addon/surface.json do editor, e só oferece a instalação fixada e verificada por checksum com o seu consentimento. Nunca substitui uma configuração do Neovim existente sem aprovação explícita, e nunca é obrigatório.

Como o usam os agentes de programação?

Foi pensado para pessoas e para agentes de programação que vivem num terminal. Os seus atalhos são fixados por testes de contrato, pelo que a memória muscular, e o que um agente espera, sobrevivem às atualizações.

Que versão obtenho?

O instalador instala a versão a que pertence — hoje, v0.5.0 — a menos que escolha outra com --version ou DWP_VIM_VERSION: uma versão exata, um mínimo >= ou latest. DWP_VIM_REF aceita um ramo ou um commit; DWP_VIM_REF=main segue o main. Esta página descreve a versão v0.5.0, que inclui todas as funcionalidades aqui listadas.

Sob que licença está e de onde vem?

GPL-3.0. Deriva do mu-vim, de Andrés M Prieto, e o crédito mantém-se no repositório.

Código-fonte e licença

O código-fonte está no repositório do DeepWorkPlan Vim. É público e tem licença GPL-3.0, derivado do mu-vim.

Entradas relacionadas do kit

• Devcontainer — ambiente de desenvolvimento reproduzível (primeiro addon)
• Dailybot — relatórios do ciclo de vida do plano visíveis para a equipa (segundo addon)
• AI Diff Reviewer — revisão local durante as revisões finais do plano (quinto addon)
• Herdr — delegar uma tarefa a um agente par num painel do Herdr (v7)
• Agentkit — um único comando para cada agente de programação de terminal, e delegação headless (v7)