Construiește un Bookmark Manager Full-Stack cu OpenCode în 30 de minute (pas cu pas)

Ce Construim

Uită de listele de caracteristici. Cel mai bun mod de a învăța un instrument este să construiești ceva cu el.

În acest tutorial, vei folosi OpenCode — agentul de coding AI open-source cu peste 120K stele pe GitHub — pentru a construi un manager de semne de carte complet de la zero. Aplicația va avea:

• Un REST API cu Express.js și TypeScript
• O bază de date SQLite cu full-text search
• Un sistem de etichete pentru organizarea semnelor de carte
• Un frontend simplu dar funcțional
• Teste unitare

Fiecare caracteristică OpenCode este introdusă în momentul în care ai nevoie de ea — nu într-o secțiune abstractă de caracteristici. Până la final, vei ști cum să instalezi OpenCode, să configurezi modele, să folosești modurile Build și Plan, să setezi servere MCP și să creezi agenți personalizați — toate acestea pentru că le-ai folosit pentru a construi un proiect real.

Timp: ~30 minute Cerințe preliminare: Node.js 18+ instalat, un terminal (macOS, Linux sau WSL pe Windows) Cost: Gratuit (folosind modelele OpenCode Zen)

Faza 1: Instalarea OpenCode și Configurarea Proiectului (5 minute)

Instalarea OpenCode

Deschide terminalul și rulează una dintre aceste comenzi:

# Option 1: npm (recommended)
npm i -g opencode-ai@latest

# Option 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

# Option 3: One-line installer
curl -fsSL https://opencode.ai/install.sh | bash

Verifică instalarea:

opencode --version

Ar trebui să vezi numărul versiunii. Începând cu martie 2026, cea mai recentă versiune stabilă este disponibilă pe depozitul GitHub OpenCode.

Creează Directorul Proiectului

mkdir bookmark-manager && cd bookmark-manager
git init
npm init -y

Lansează OpenCode pentru Prima Dată

opencode

Aceasta deschide TUI (Terminal User Interface) al OpenCode — o interfață interactivă pe tot ecranul construită cu Bubble Tea. Vei vedea o intrare de chat în partea de jos și un panou de conversație în zona principală.

Alege un Model

La prima lansare, OpenCode îți va cere să selectezi un model. Ai trei căi:

Gratuit (modele Zen): Tastează /models și selectează unul dintre modelele Zen gratuite. Pentru acest tutorial, Grok Code Fast 1 sau GLM 4.7 funcționează bine. Acestea sunt gratuite și nu necesită o cheie API.

Local (Ollama): Dacă ai Ollama instalat, OpenCode îl va detecta automat. Modelul recomandat pentru Ollama este glm-4.7:cloud.

Plătit (adu-ți propria cheie): Tastează /connect pentru a conecta cheia ta API de la Anthropic, OpenAI sau Google. Cheile sunt stocate local în ~/.local/share/opencode/auth.json.

Pentru acest tutorial, orice model funcționează. Modelele cu capacități mai mari (Claude Sonnet 4.6, GPT-5.4) vor produce rezultate mai bune pentru sarcini complexe, dar modelele gratuite Zen gestionează tot ce construim aici.

Faza 2: Structurarea Proiectului cu Build mode (4 minute)

OpenCode pornește în Build mode în mod implicit. Build mode oferă agentului AI acces complet pentru a crea fișiere, a edita cod și a rula comenzi. Aceasta este ceea ce ne dorim pentru structurare.

Primul tău Prompt

Tastează acest mesaj în chat-ul OpenCode:

Set up a TypeScript Node.js project with Express for a bookmark manager REST API.
Use SQLite via better-sqlite3 for the database. Add TypeScript, ts-node, and
nodemon as dev dependencies. Create a src/ directory with an index.ts entry point
that starts an Express server on port 3000.

OpenCode va:

1. Crea un tsconfig.json
2. Instala dependențele cu npm install
3. Crea src/index.ts cu setarea serverului Express
4. Actualiza package.json cu scripturi de pornire

Urmărește TUI — vei vedea agentul executând comenzi de terminal, creând fișiere și explicând ce face la fiecare pas. Aceasta nu este doar generare de cod în vid; OpenCode are acces complet la sistemul tău de fișiere și la terminal.

Verifică dacă Funcționează

Odată ce OpenCode termină, spune-i:

Run the server and verify it starts correctly on port 3000.

OpenCode va rula npx nodemon src/index.ts și va confirma că serverul ascultă. Ar trebui să vezi un output precum Server running on http://localhost:3000.

Ce s-a întâmplat (Caracteristică: Build Mode)

Build mode este agentul implicit al OpenCode. Acesta are acces la toate instrumentele: citire/scriere fișiere, execuție în terminal și editare de cod. Conform documentației OpenCode, te poți gândi la el ca la un programator AI de tip pair cu acces complet la mediul tău de dezvoltare.

Faza 3: Crearea Modelului de Date și a Bazei de Date (4 minute)

Proiectează Schema

Tastează acest prompt:

Create a database module at src/db.ts that:
1. Initializes a SQLite database at ./data/bookmarks.db
2. Creates a bookmarks table with: id (auto-increment), url (text, unique),
   title (text), description (text, nullable), created_at (datetime),
   updated_at (datetime)
3. Creates a tags table with: id (auto-increment), name (text, unique)
4. Creates a bookmark_tags junction table for many-to-many relationships
5. Enables WAL mode for concurrent read performance
6. Creates an FTS5 virtual table for full-text search on title and description
Export a function to get the database instance.

OpenCode va genera întregul modul de bază de date. Acordă atenție modului în care gestionează configurarea FTS5 (Full-Text Search 5) — aceasta este o caracteristică SQLite care va alimenta funcționalitatea noastră de căutare mai târziu.

Inițializează Baza de Date la Pornirea Serverului

Import the database module in index.ts and initialize it when the server starts.
Log a confirmation message.

Creează Configurația opencode.json

Acesta este un moment bun pentru a introduce configurația proiectului. Creează un fișier spunându-i lui OpenCode:

Create an opencode.json file in the project root with the project name
"bookmark-manager" and a rule that says "This is a TypeScript Express API
using better-sqlite3. Follow RESTful conventions. Use async/await. Return
JSON responses with consistent error formatting."

Aceasta creează fișierul de configurare a proiectului pe care OpenCode îl citește la pornire. Acesta oferă AI-ului context persistent despre proiectul tău — standarde de codare, decizii de arhitectură și constrângeri — astfel încât să nu trebuiască să le repeți în fiecare prompt.

Faza 4: Construirea Endpoint-urilor REST API (5 minute)

Generează Rutele

Create a routes module at src/routes/bookmarks.ts with these endpoints:
- POST /api/bookmarks — create a bookmark (validate url and title are present)
- GET /api/bookmarks — list all bookmarks with pagination (page, limit params)
- GET /api/bookmarks/:id — get a single bookmark with its tags
- PUT /api/bookmarks/:id — update a bookmark
- DELETE /api/bookmarks/:id — delete a bookmark and its tag associations
Use proper HTTP status codes. Return JSON with a consistent shape:
{ success: boolean, data: any, error?: string }

Înregistrează Rutele

Import the bookmark routes in index.ts and register them. Also add
express.json() middleware and a global error handler.

Testează cu curl

Start the server, then create a test bookmark using curl:
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Then fetch all bookmarks to verify it was saved.

OpenCode va executa aceste comenzi în terminalul tău și îți va arăta răspunsurile. Aici strălucește instrumentul — nu părăsești niciodată terminalul, iar AI-ul își verifică propria muncă.

Faza 5: Adăugarea Căutării cu FTS5 (4 minute)

Introducerea Plan mode

Înainte de a construi căutarea, să folosim Plan mode pentru a ne gândi la implementare. Comută modurile:

/plan

Acum ești în Plan mode. AI-ul poate să-ți citească codul și să-l analizeze, dar nu poate modifica niciun fișier. Acest lucru este util pentru planificarea înainte de a face modificări.

Analyze my current database schema and FTS5 table. Plan how to implement a
search endpoint that queries the FTS5 table and returns bookmarks ranked by
relevance. Consider edge cases: empty queries, special characters, partial
matches.

OpenCode îți va examina codul, va scrie un plan în .opencode/plans/ și își va explica abordarea fără a atinge niciun fișier. Citește planul, ajustează-l dacă este necesar, apoi comută înapoi:

/build

Implementează Căutarea

Based on the plan, implement a GET /api/bookmarks/search?q=query endpoint
that uses the FTS5 virtual table for full-text search. Include snippet
highlighting and relevance ranking. Handle edge cases from the plan.

Testează Căutarea

Create three more test bookmarks with different titles and descriptions,
then test the search endpoint with a query that should match two of them.

Ce s-a întâmplat (Caracteristică: Plan Mode)

Fluxul de lucru Plan/Build este modul în care dezvoltatorii experimentați folosesc OpenCode pentru sarcini complexe. Planifică mai întâi, revizuiește abordarea, apoi construiește. Fișierele de plan sunt salvate în .opencode/plans/ și pot fi referite ulterior de către agentul de build. Acest lucru previne luarea de decizii structurale mari din mers de către AI.

Faza 6: Implementarea Sistemului de Etichete (4 minute)

Creează Endpoint-urile pentru Etichete

Create a routes module at src/routes/tags.ts with:
- POST /api/tags — create a new tag
- GET /api/tags — list all tags with bookmark counts
- POST /api/bookmarks/:id/tags — add a tag to a bookmark
- DELETE /api/bookmarks/:id/tags/:tagId — remove a tag from a bookmark
- GET /api/bookmarks?tag=tagname — filter bookmarks by tag (update existing
  list endpoint to support this query parameter)
Register the tag routes in index.ts.

Testează Fluxul de Etichete

Create two tags: "dev-tools" and "tutorials". Add the "dev-tools" tag to
the OpenCode bookmark. Then fetch bookmarks filtered by the "dev-tools" tag.

Faza 7: Construirea unui Frontend Simplu (5 minute)

Generează Frontend-ul

Create a public/ directory with a single-page frontend:
- index.html with a clean, minimal design (no framework, just HTML/CSS/JS)
- A form to add bookmarks (url, title, description)
- A search bar that queries the search endpoint with debounced input
- A list of bookmarks showing title, url, tags, and a delete button
- A tag filter sidebar that shows all tags with counts
- Use fetch() for API calls. Mobile responsive. No build step needed.
Serve the public/ directory as static files from Express.

OpenCode va genera frontend-ul complet — structura HTML, stilizarea CSS și JavaScript pentru interacțiunile API — dintr-o singură trecere. Avantajul construirii acestuia în terminal cu un agent AI este că acesta poate testa imediat dacă frontend-ul se conectează la API.

Testează Full Stack-ul

Start the server, open http://localhost:3000 in a description, and verify
that adding a bookmark from the form, searching, and filtering by tag all
work correctly.

Faza 8: Adăugarea Testelor cu un Agent Personalizat (5 minute)

Creează un Agent de Test Personalizat

Aici intervine caracteristica agenți personalizați a OpenCode. În loc să folosim agentul generic Build pentru testare, vom crea unul specializat.

Adaugă acest fragment în opencode.json:

{
  "agents": {
    "test": {
      "name": "Test Writer",
      "instructions": "You are a testing specialist. Write comprehensive tests using Vitest. Focus on edge cases and error paths. Never modify source code — only create and edit test files.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

Acum comută la agentul de test:

/agent test

Generează Teste

Write comprehensive tests for the bookmark API using Vitest and supertest.
Cover:
- Creating a bookmark with valid data
- Creating a bookmark with missing required fields
- Fetching all bookmarks with pagination
- Searching with FTS5 (matching and non-matching queries)
- Adding and removing tags
- Deleting a bookmark removes its tag associations
Use an in-memory SQLite database for test isolation.

Rulează Testele

Install vitest and supertest as dev dependencies, add a test script to
package.json, then run the test suite.

Ce s-a întâmplat (Caracteristică: Agenți Personalizați)

Agenții personalizați îți permit să creezi persone axate pe instrucțiuni specifice și acces la instrumente. Agentul de test pe care l-am creat poate doar să citească fișiere, să scrie fișiere de test și să ruleze comenzi de terminal — nu poate modifica codul sursă. Această constrângere previne problema comună a AI-ului care „repară” codul sursă atunci când testele eșuează, în loc să repare testele.

Poți crea agenți pentru orice flux de lucru specializat: code review, documentație, migrări de baze de date, scripturi DevOps. Documentația agenților OpenCode are mai multe exemple.

Bonus: Conectarea unui Server MCP pentru Funcționalitate Îmbunătățită

Dacă dorești să extinzi managerul tău de semne de carte, poți conecta instrumente externe prin servere MCP (Model Context Protocol).

Exemplu: Adăugarea unui Server MCP de Previzualizare a Link-urilor

Imaginează-ți că dorești ca OpenCode să preia automat metadatele (titlu, descriere, favicon) de la URL-uri atunci când creezi semne de carte. Poți conecta un server MCP care face preluare HTTP:

Adaugă acest fragment în opencode.json:

{
  "mcp": {
    "link-preview": {
      "type": "local",
      "command": ["npx", "link-preview-mcp-server"]
    }
  }
}

Acum OpenCode are un instrument nou disponibil: poate prelua metadate de URL ca parte a fluxului său de lucru. Când îi ceri să „adauge un semn de carte pentru https://example.com și să completeze automat titlul și descrierea”, acesta va folosi serverul MCP pentru a prelua acele date.

Servere MCP Remote

Pentru servicii cloud, folosește servere MCP remote cu gestionare automată OAuth:

{
  "mcp": {
    "cloud-storage": {
      "type": "remote",
      "url": "https://mcp.example.com/storage",
      "headers": {
        "Authorization": "Bearer ${STORAGE_TOKEN}"
      }
    }
  }
}

OpenCode detectează răspunsurile 401 și inițiază automat fluxul OAuth dacă serverul acceptă Dynamic Client Registration.

Bonus: Utilizarea OpenCode în CI/CD

OpenCode are un mod CLI care rulează fără TUI — perfect pentru automatizare. Îl poți folosi în GitHub Actions sau în orice pipeline CI:

# Run a single prompt and exit
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Use a specific model
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

Pentru managerul nostru de semne de carte, ai putea adăuga un pas CI care rulează OpenCode pentru a revizui PR-urile automat. Integrarea GitHub OpenCode oferă o versiune mai simplificată a acestui flux de lucru.

Structura Completă a Proiectului

După urmarea acestui tutorial, proiectul tău ar trebui să arate astfel:

bookmark-manager/
  opencode.json          # Config proiect OpenCode + agenți personalizați + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Punct de intrare server Express
    db.ts                # Modul bază de date SQLite cu FTS5
    routes/
      bookmarks.ts       # Endpoint-uri CRUD + căutare
      tags.ts            # Endpoint-uri gestionare etichete
  public/
    index.html           # Frontend single-page
  tests/
    bookmarks.test.ts    # Suită teste API
  data/
    bookmarks.db         # Bază de date SQLite (gitignored)
  .opencode/
    plans/               # Planuri din sesiunile Plan mode

Ce ai Învățat

Prin construirea unui proiect real, ai exersat aceste capacități OpenCode:

Diferența cheie între OpenCode și alte instrumente de coding AI este că este în întregime open source, rulează în terminalul tău și nu stochează codul sau datele tale de context. Tu controlezi modelele, datele rămân locale, iar comunitatea de peste 800 de contributori îl face să evolueze rapid.

Pentru echipele care folosesc mai multe instrumente AI, OpenCode funcționează bine ca o completare bazată pe terminal pentru asistenții IDE. La ZBuild, îl folosim adesea alături de instrumentele bazate pe editor pentru diferite părți ale fluxului de lucru de dezvoltare.

Pașii Următori

Acum că ai un manager de semne de carte funcțional și o înțelegere solidă a OpenCode, iată câteva direcții de explorat:

1. Adaugă autentificare — Folosește agentul Build pentru a adăuga autentificare bazată pe JWT cu conturi de utilizator
2. Deploy în producție — Cere-i lui OpenCode să genereze un Dockerfile și să facă deploy pe Fly.io sau Railway
3. Construiește o extensie de browser — Creează o extensie Chrome care adaugă semne de carte prin API
4. Explorează mai multe modele Zen — Încearcă Big Pickle, MiniMax M2.1, sau rulează un model local prin Ollama
5. Creează mai mulți agenți personalizați — Un agent de „refactorizare”, un agent de „documentație” sau un agent de „audit de securitate”

Documentația OpenCode și depozitul awesome-opencode au mai multe plugin-uri, teme și configurații ale comunității de explorat.

Surse

• OpenCode — Documentație Oficială
• OpenCode — Depozit GitHub
• OpenCode — Modele Zen
• OpenCode — Documentație Agenți
• OpenCode — Servere MCP
• OpenCode — Mod CLI
• OpenCode — Configurare
• OpenCode — Integrare GitHub
• Ollama — Integrare OpenCode
• awesome-opencode — Resurse Comunitate
• Composio — MCP cu OpenCode
• Computing for Geeks — Setup OpenCode AI