A termfy-database dá ao binário um banco SQLite quando a spec pede que
ele guarde registros entre execuções. Ela copia os stubs de template/db/,
cria as tabelas por migration, escreve um repositório por tabela e liga
esse repositório aos commands, tools e screens. No fim, você tem o arquivo
~/.<bin>/data.db, migrations embutidas no executável, testes com banco em
memória verdes e o binário compilado aplicando o schema fora do
repositório.
Quando usar
Use esta skill quando a spec aberta descrever informações que precisam sobreviver ao fim do processo:
- um histórico de consultas que você quer rever depois,
- um cache local de pedidos baixados da API da loja,
- uma fila de tarefas que o binário processa aos poucos,
- notas ou registros próprios, criados pelo CLI e lidos pela TUI.
Não use para preferências nem para segredos. Preferência é key de
settings.json, declarada pela termfy-config. Token e
senha vão para o cofre, também pela termfy-config. Se a necessidade de
guardar registros aparecer no meio de outra tarefa, volte à
termfy-spec para registrar a mudança antes de implementar.
O esqueleto recebe o banco apenas quando você solicita esse armazenamento.
Como pedir
Para criar o banco pela primeira vez:
Use a skill termfy-database para implementar a spec 0003, que guarda notas locais na tabela
notese expõe os commandsdb statusedb migrate.
Para evoluir uma tabela que já saiu em release:
Use a skill termfy-database para acrescentar a coluna
pinnedà tabelanotes, conforme a spec 0004, sem editar a migration já publicada.
Para levar o repositório aos três modos:
Use a skill termfy-database para ligar o repositório de notas ao command
notes list, a uma tool MCP e a uma screen da TUI.
O que a skill faz
- Roda
git status --shorte lê a spec aberta emspecs/. Ela confere que a seção Surface lista as tabelas com colunas e que o Design descreve a migration. Se faltar, ela devolve o trabalho àtermfy-spec. - Na primeira vez no projeto, copia
template/db/database.tsparasrc/db/database.tsetemplate/db/migrations/index.tsparasrc/db/migrations/index.ts, trocando os imports../../src/por../. - Troca o import da migration de notes no
index.tspela primeira migration da spec. A tabela de exemplo só fica quando a spec pede. - Cria a migration em
src/db/migrations/NNNN-<name>.ts, com a próxima versão. Em seguida, registra a migration noindex.ts. - Cria o repositório de cada tabela em
src/db/<resource>.ts, a partir detemplate/db/repository.ts. - Quando a spec pede
db statusedb migrate, copiatemplate/db/command.tsparasrc/cli/commands/db.tse registra emsrc/cli/commands.ts. - Liga o repositório aos commands, tools e screens: abre o banco no
rune fecha emfinally. - Escreve os testes em
tests/<resource>.test.ts, a partir detemplate/db/example-test.ts. - Documenta o banco em
docs/configuration.mde os commands novos emdocs/cli.md. - Roda
bun run builde executa o binário dedist/numa pasta vazia, com<BIN>_HOMEtemporário, para provar que as migrations estão embutidas. - Confere à mão cada tabela de Surface contra os
CREATE TABLEeALTER TABLEdas migrations. - Roda
bun run validatee marca[x]nas tarefas#termfy-databaseconcluídas na spec.
Exemplo
A spec pede uma tabela de notas. A migration é o stub
0001-create-notes.ts, copiado para src/db/migrations/:
import type { Migration } from "./index.ts";
export const createNotes: Migration = { version: 1, name: "create_notes", up: ` CREATE TABLE notes ( id INTEGER PRIMARY KEY, title TEXT NOT NULL, body TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL ) STRICT; CREATE INDEX notes_created_at ON notes (created_at); `,};O registro importa cada migration de forma estática. checkMigrations()
roda na importação e recusa lacuna de versão ou SQL vazio:
import { createNotes } from "./0001-create-notes.ts";
export const migrations: readonly Migration[] = checkMigrations([createNotes]);O repositório em src/db/notes.ts concentra o SQL da tabela. Cada função
recebe o Database aberto e usa parâmetros nomeados:
export function getNote(db: Database, id: number): Note { const row = db.query<NoteRow, { id: number }>( "SELECT id, title, body, created_at FROM notes WHERE id = $id", ).get({ id }); if (!row) throw new AppError(ExitCode.NOT_FOUND, `Note ${id} not found.`); return toNote(row);}O teste abre um banco :memory: por caso. Assim os testes não usam ~/.<bin>/:
describe("notes repository", () => { let db: Database; beforeEach(() => { db = openDatabase(":memory:"); }); afterEach(() => db.close());
test("adds, lists, reads and removes", () => { const note = addNote(db, { title: "First" }, new Date("2026-11-10T12:00:00.000Z")); expect(listNotes(db)).toEqual([note]); expect(getNote(db, note.id).title).toBe("First"); removeNote(db, note.id); expect(listNotes(db)).toEqual([]); });
test("a database newer than the binary is refused", () => { db.run("PRAGMA user_version = 999"); expect(() => migrate(db)).toThrow(AppError); });});Meses depois, a spec 0004 pede notas fixadas. A migration 0001 já saiu em
release, então a skill cria 0002-add-notes-pinned.ts com
ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0 e acrescenta
addNotesPinned à lista do index.ts. Ao abrir um banco na versão 1,
migrate() copia o arquivo para data.db.v1.bak antes de aplicar a 2.
A seção Surface da spec lista a tabela. A linha vai para ### Storage
do CLISPEC.md quando a spec fecha:
| Tabela | Coluna | Tipo | Chave primária | Not null || --- | --- | --- | --- | --- || `notes` | `id` | `INTEGER` | sim | sim || `notes` | `title` | `TEXT` | não | sim || `notes` | `body` | `TEXT` | não | sim || `notes` | `created_at` | `TEXT` | não | sim |Regras que a skill segue
- Banco previsto na spec. A pasta
src/db/só aparece quando a spec descreve os registros a preservar, mantendo SQLite opcional no projeto. - Um arquivo por binário. O banco fica em
~/.<bin>/data.db, obtido pordatabasePath(). Com<BIN>_HOME, testes e CI usam uma pasta descartável. - Schema muda só por migration. Uma migration por arquivo, versões a partir de 1, em sequência. Migration publicada não é editada, porque bancos já instalados aplicaram a versão antiga.
- Import estático. O registro importa cada arquivo para o build embutir
o SQL. O binário compilado roda onde o repositório não existe, então ler
.sqldo disco quebraria a instalação. openDatabase()aplica as pendentes. Ele liga foreign keys, usa WAL e aplica cada migration na sua transação. Um banco mais novo que o binário é recusado com exit code 3, para que uma versão antiga não grave sobre um schema que ela não conhece.bun:sqlite, sem ORM. O driver incluído no Bun entra no executável, dispensando uma dependência adicional nopackage.json.- SQL só no repositório. Commands, tools e screens chamam as mesmas funções. Os três modos leem e gravam do mesmo jeito.
- Segredo fica no cofre. Token lido por
getCredential()não vai para tabela, porquedata.dbnão é cifrado. - Erros viram
AppError. CONFIG (3) para banco ilegível ou schema incompatível, PERMISSION (7) para pasta sem acesso, NOT_FOUND (6) para linha ausente. Você recebe uma mensagem correspondente à falha. - Backup no lugar de rollback. Não há migration de volta. Por isso
migrate()copia o arquivo comVACUUM INTOantes de mudar um schema existente. Para voltar, você fecha o binário e trocadata.dbpelo backup. - Tabelas na superfície. Nenhum script compara o schema com a spec. A
skill confere lendo as migrations. A
termfy-reviewrepete a leitura.
O que ela entrega
No relatório final, a skill lista:
- as tabelas criadas e a versão do schema,
- os arquivos novos, em geral
src/db/database.ts,src/db/migrations/index.ts,src/db/migrations/NNNN-<name>.ts,src/db/<resource>.tsetests/<resource>.test.ts, src/cli/commands/db.tse o registro emsrc/cli/commands.ts, quando a spec pededb statusedb migrate,- os commands, tools e screens que usam o banco,
- o resultado dos testes e do binário compilado numa pasta vazia,
- as alterações em
docs/configuration.mdedocs/cli.md, - os itens
#termfy-databasemarcados na spec.
Próxima skill
Com o repositório pronto, siga para a termfy-cli ou a termfy-command-set, que criam os commands que chamam as funções. Depois vêm a termfy-mcp, a termfy-tui e a termfy-test.