dude-claude-plugin 2026.2.14 → 2026.2.19

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dude",
-  "version": "2026.2.14",
+  "version": "2026.2.19",
   "description": "Ultra-minimal RAG and cross-project memory for Claude CLI",
   "author": {
     "name": "Fingerskier"

package/README.md

@@ -20,7 +20,7 @@ claude plugin install dude-claude-plugin@fingerskier-plugins
 
 ### MCP server only (via npx)
 
-If you just want the 6 MCP tools without auto-hooks:
+If you just want the 7 MCP tools without auto-hooks:
 
 ```bash
 claude mcp add dude -- npx dude-claude-plugin mcp
@@ -37,12 +37,13 @@ claude mcp add dude -- dude-claude mcp
 
 | Component | Description |
 |-----------|-------------|
-| **MCP server** | 6 tools: `search`, `upsert_record`, `get_record`, `list_records`, `delete_record`, `list_projects` |
+| **MCP server** | 7 tools: `search`, `upsert_record`, `get_record`, `list_records`, `delete_record`, `list_projects`, `sync_status` |
 | **Auto-retrieve hook** | On each prompt, searches memory for relevant context and injects it |
 | **Auto-persist hook** | After each response, classifies the work and saves issues/specs |
 | **Web UI** | Local dashboard at `http://127.0.0.1:3456` for manual CRUD |
-| **Storage** | SQLite + sqlite-vec at `~/.dude-claude/dude.db` |
+| **Storage** | libsql (SQLite-compatible) at `~/.dude-claude/dude-libsql.db` |
 | **Embeddings** | Local all-MiniLM-L6-v2 via @huggingface/transformers (no API keys) |
+| **Cloud sync** | Optional Turso cloud sync via environment variables |
 
 ## How it works
 
@@ -62,7 +63,17 @@ npx dude-claude-plugin serve
 dude-claude serve
 ```
 
-Opens a local dashboard on port 3456 for browsing and editing projects, issues, and specifications.
+Opens a local dashboard at `http://127.0.0.1:3456` (auto-opens in your browser). The UI has two panels: a sidebar listing records with filters, and a main panel for viewing and editing.
+
+**What you can do:**
+
+- **Project selector** — filter records by project or view all projects at once
+- **Semantic search** — type in the search bar to find records by meaning, not just keywords (results ranked by similarity)
+- **Filter by kind** — narrow to issues, specs, arch decisions, updates, or tests
+- **Filter by status** — open, resolved, archived, active, or inactive
+- **Create / edit / delete** — click "+ New" to add a record, click any record to edit it, or delete from the detail view
+
+Set `DUDE_PORT` to change the default port (see [Configuration](#configuration)).
 
 ## Configuration
 
@@ -70,6 +81,19 @@ Opens a local dashboard on port 3456 for browsing and editing projects, issues,
 |---|---|---|
 | `DUDE_PORT` | `3456` | Web UI port |
 | `DUDE_CONTEXT_LIMIT` | `5` | Max records injected per prompt |
+| `DUDE_RECENCY_HOURS` | `1` | Lookback window for recent records |
+
+### Cloud Sync (optional)
+
+The plugin works fully offline by default. To enable cloud sync with [Turso](https://turso.tech), set these environment variables:
+
+| Env variable | Description |
+|---|---|
+| `DUDE_TURSO_URL` | Turso database URL (e.g. `libsql://your-db.turso.io`) |
+| `DUDE_TURSO_TOKEN` | Turso auth token |
+| `DUDE_SYNC_INTERVAL` | Sync interval in ms (default: `60000`) |
+
+When configured, `@libsql/client` maintains a local embedded replica that auto-syncs with Turso. You can also trigger a manual sync via the `sync_status` MCP tool or `POST /api/sync`.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dude-claude-plugin",
-  "version": "2026.2.14",
+  "version": "2026.2.19",
   "description": "Ultra-minimal RAG and cross-project memory for Claude CLI",
   "type": "module",
   "bin": {

package/scripts/dump-local.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Export the local libsql database as SQL INSERT statements.
+ *
+ * Usage:
+ *   node scripts/dump-local.js > dump.sql
+ *   turso db shell <dbname> < dump.sql
+ *
+ * Reads from ~/.dude-claude/dude-libsql.db (or DUDE_DB_PATH env override).
+ * Outputs projects first, then records (with vector embeddings), to stdout.
+ */
+
+import { createClient } from '@libsql/client';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const DATA_DIR = join(homedir(), '.dude-claude');
+const DB_PATH = process.env.DUDE_DB_PATH || join(DATA_DIR, 'dude-libsql.db');
+
+function esc(str) {
+  if (str == null) return 'NULL';
+  return "'" + String(str).replace(/'/g, "''") + "'";
+}
+
+function parseEmbedding(blob) {
+  if (!blob) return null;
+  if (blob instanceof Float32Array) return blob;
+  if (blob instanceof ArrayBuffer) return new Float32Array(blob);
+  if (ArrayBuffer.isView(blob)) {
+    return new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
+  }
+  if (typeof blob === 'string') return new Float32Array(JSON.parse(blob));
+  return null;
+}
+
+async function main() {
+  const db = createClient({ url: `file:${DB_PATH}` });
+
+  // -- Projects --
+  const projects = await db.execute('SELECT * FROM project ORDER BY id');
+  for (const p of projects.rows) {
+    console.log(
+      `INSERT INTO project (id, name, created_at, updated_at) VALUES (${p.id}, ${esc(p.name)}, ${esc(p.created_at)}, ${esc(p.updated_at)});`
+    );
+  }
+
+  // -- Records (with embeddings) --
+  const records = await db.execute('SELECT * FROM record ORDER BY id');
+  for (const r of records.rows) {
+    const emb = parseEmbedding(r.embedding);
+    const embExpr = emb
+      ? `vector('${JSON.stringify(Array.from(emb))}')`
+      : 'NULL';
+
+    console.log(
+      `INSERT INTO record (id, project_id, kind, title, body, status, embedding, created_at, updated_at) VALUES (${r.id}, ${r.project_id}, ${esc(r.kind)}, ${esc(r.title)}, ${esc(r.body)}, ${esc(r.status)}, ${embExpr}, ${esc(r.created_at)}, ${esc(r.updated_at)});`
+    );
+  }
+
+  db.close();
+  console.error(`[dump] Exported ${projects.rows.length} projects, ${records.rows.length} records`);
+}
+
+main().catch(err => {
+  console.error('dump-local failed:', err);
+  process.exit(1);
+});

package/src/db-adapter.js

@@ -77,6 +77,22 @@ export class DbAdapter {
     throw new Error('Not implemented');
   }
 
+  /**
+   * Get cloud sync status.
+   * @returns {Promise<{ enabled: boolean, syncUrl?: string, syncInterval?: number }>}
+   */
+  async syncStatus() {
+    return { enabled: false };
+  }
+
+  /**
+   * Trigger a manual cloud sync (no-op if sync is not configured).
+   * @returns {Promise<{ synced: boolean, message: string }>}
+   */
+  async sync() {
+    return { synced: false, message: 'Cloud sync not configured' };
+  }
+
   /**
    * Close the database connection.
    */

package/src/db-libsql.js

@@ -21,6 +21,7 @@ export class LibsqlAdapter extends DbAdapter {
     this.config = config;
     this.db = null;
     this.currentProject = null;
+    this._syncError = null;
   }
 
   // ---------------------------------------------------------------------------
@@ -30,12 +31,33 @@ export class LibsqlAdapter extends DbAdapter {
   async init() {
     if (this.db) return;
     this._ensureDataDir();
-    this.db = this._createClient();
+    this._syncError = null;
+
+    if (this._hasSyncConfig()) {
+      try {
+        this.db = this._createClient();  // tries sync-enabled client
+      } catch (err) {
+        console.error(`[dude] Cloud sync connection failed: ${err.message}`);
+        console.error('[dude] Falling back to local-only mode.');
+        this._syncError = err.message;
+        this.db = this._createLocalOnlyClient();
+      }
+    } else {
+      this.db = this._createLocalOnlyClient();
+    }
+
     await this._runSchema();
     const projectName = this._detectProject();
     this.currentProject = await this._upsertProject(projectName);
     await this._migrateProjectNames(projectName);
-    console.error(`[dude] LibSQL DB ready — project "${this.currentProject.name}" (id=${this.currentProject.id})`);
+
+    const syncInfo = await this.syncStatus();
+    const syncMsg = syncInfo.enabled
+      ? ` | cloud sync → ${syncInfo.syncUrl}`
+      : syncInfo.error
+        ? ' | cloud sync FAILED — local-only mode'
+        : '';
+    console.error(`[dude] LibSQL DB ready — project "${this.currentProject.name}" (id=${this.currentProject.id})${syncMsg}`);
   }
 
   _ensureDataDir() {
@@ -44,6 +66,15 @@ export class LibsqlAdapter extends DbAdapter {
     }
   }
 
+  _hasSyncConfig() {
+    return !!(this.config.syncUrl || process.env.DUDE_TURSO_URL);
+  }
+
+  _createLocalOnlyClient() {
+    const url = this.config.url || `file:${this.config.dbPath || DB_PATH}`;
+    return createClient({ url });
+  }
+
   _createClient() {
     const url = this.config.url
       || `file:${this.config.dbPath || DB_PATH}`;
@@ -53,8 +84,8 @@ export class LibsqlAdapter extends DbAdapter {
     if (this.config.syncUrl || process.env.DUDE_TURSO_URL) {
       opts.syncUrl = this.config.syncUrl || process.env.DUDE_TURSO_URL;
       opts.authToken = this.config.authToken || process.env.DUDE_TURSO_TOKEN;
-      const interval = this.config.syncInterval || process.env.DUDE_SYNC_INTERVAL;
-      if (interval) opts.syncInterval = parseInt(interval);
+      const interval = this.config.syncInterval || process.env.DUDE_SYNC_INTERVAL || 60000;
+      opts.syncInterval = parseInt(interval);
     }
 
     return createClient(opts);
@@ -74,10 +105,10 @@ export class LibsqlAdapter extends DbAdapter {
         sql: `CREATE TABLE IF NOT EXISTS record (
           id         INTEGER PRIMARY KEY AUTOINCREMENT,
           project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
-          kind       TEXT NOT NULL CHECK (kind IN ('issue','spec','arch','update')),
+          kind       TEXT NOT NULL,
           title      TEXT NOT NULL,
           body       TEXT NOT NULL DEFAULT '',
-          status     TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open','resolved','archived')),
+          status     TEXT NOT NULL DEFAULT 'open',
           embedding  F32_BLOB(384),
           created_at TEXT NOT NULL DEFAULT (datetime('now')),
           updated_at TEXT NOT NULL DEFAULT (datetime('now'))
@@ -92,6 +123,50 @@ export class LibsqlAdapter extends DbAdapter {
               ON record(libsql_vector_idx(embedding, 'metric=cosine'))`,
       },
     ], 'write');
+
+    // Migrate existing databases that still have CHECK constraints
+    await this._migrateDropChecks();
+  }
+
+  /**
+   * Detect whether the record table was created with CHECK constraints
+   * (from a previous schema version) and recreate it without them.
+   * This is needed because SQLite/libsql doesn't support ALTER TABLE
+   * to drop constraints — the table must be recreated.
+   */
+  async _migrateDropChecks() {
+    const result = await this.db.execute(
+      "SELECT sql FROM sqlite_master WHERE type='table' AND name='record'",
+    );
+    const ddl = result.rows[0]?.sql || '';
+    if (!ddl.includes('CHECK')) return; // already migrated or fresh DB
+
+    await this.db.executeMultiple(`
+      CREATE TABLE record_new (
+        id         INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+        kind       TEXT NOT NULL,
+        title      TEXT NOT NULL,
+        body       TEXT NOT NULL DEFAULT '',
+        status     TEXT NOT NULL DEFAULT 'open',
+        embedding  F32_BLOB(384),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      INSERT INTO record_new SELECT * FROM record;
+
+      DROP TABLE record;
+
+      ALTER TABLE record_new RENAME TO record;
+
+      CREATE INDEX IF NOT EXISTS idx_record_project_kind
+        ON record(project_id, kind);
+
+      CREATE INDEX IF NOT EXISTS idx_record_embedding
+        ON record(libsql_vector_idx(embedding, 'metric=cosine'));
+    `);
+    console.error('[dude] Migrated record table: removed CHECK constraints');
   }
 
   _detectProject() {
@@ -369,6 +444,48 @@ export class LibsqlAdapter extends DbAdapter {
     return this.get(Number(result.lastInsertRowid));
   }
 
+  async syncStatus() {
+    const syncUrl = this.config.syncUrl || process.env.DUDE_TURSO_URL || null;
+    const syncInterval = this.config.syncInterval
+      || process.env.DUDE_SYNC_INTERVAL
+      || (syncUrl ? 60000 : null);
+    return {
+      enabled: !!syncUrl && !this._syncError,
+      ...(syncUrl ? { syncUrl } : {}),
+      ...(syncInterval ? { syncInterval: parseInt(syncInterval) } : {}),
+      ...(this._syncError ? { error: this._syncError, degraded: true } : {}),
+    };
+  }
+
+  async sync() {
+    if (!this._hasSyncConfig()) {
+      return { synced: false, message: 'Cloud sync not configured. Set DUDE_TURSO_URL and DUDE_TURSO_TOKEN to enable.' };
+    }
+
+    // If degraded, attempt to reconnect with sync-enabled client
+    if (this._syncError) {
+      try {
+        const newClient = this._createClient();
+        // Run a test query to verify the connection works
+        await newClient.execute('SELECT 1');
+        this.db.close();
+        this.db = newClient;
+        this._syncError = null;
+        console.error('[dude] Cloud sync reconnected successfully.');
+        return { synced: true, message: `Reconnected and synced with ${this.config.syncUrl || process.env.DUDE_TURSO_URL}` };
+      } catch (err) {
+        return { synced: false, message: `Reconnection failed: ${err.message}` };
+      }
+    }
+
+    try {
+      await this.db.sync();
+      return { synced: true, message: `Synced with ${this.config.syncUrl || process.env.DUDE_TURSO_URL}` };
+    } catch (err) {
+      return { synced: false, message: `Sync failed: ${err.message}` };
+    }
+  }
+
   async close() {
     if (this.db) {
       this.db.close();

package/src/migrations/003-drop-checks.js

@@ -0,0 +1,28 @@
+export const version = 3;
+
+export function up(db) {
+  // Remove CHECK constraints from the record table.
+  // Constraints are now enforced at the business logic layer (Zod validation).
+  // This also enables new kinds (e.g. 'test') and statuses (e.g. 'active', 'inactive')
+  // without requiring further schema migrations.
+  db.exec(`
+    CREATE TABLE record_new (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+      kind       TEXT    NOT NULL,
+      title      TEXT    NOT NULL,
+      body       TEXT    NOT NULL DEFAULT '',
+      status     TEXT    NOT NULL DEFAULT 'open',
+      created_at TEXT    NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+
+    INSERT INTO record_new SELECT * FROM record;
+
+    DROP TABLE record;
+
+    ALTER TABLE record_new RENAME TO record;
+
+    CREATE INDEX idx_record_project_kind ON record(project_id, kind);
+  `);
+}

package/src/server.js

@@ -15,10 +15,10 @@ export async function startServer() {
   // ---- search ----
   server.tool(
     'search',
-    'Semantic search across records (issues, specs, arch decisions & updates). Returns cross-project results ranked by similarity.',
+    'Semantic search across records (issues, specs, arch decisions, updates & tests). Returns cross-project results ranked by similarity.',
     {
       query: z.string().describe('Natural language search query'),
-      kind: z.enum(['issue', 'spec', 'arch', 'update', 'all']).optional().describe('Filter by record kind'),
+      kind: z.enum(['issue', 'spec', 'arch', 'update', 'test', 'all']).optional().describe('Filter by record kind'),
       project: z.string().optional().describe('Project name to boost; "*" for equal weight'),
       limit: z.number().int().positive().optional().describe('Max results (default 5)'),
     },
@@ -42,10 +42,10 @@ export async function startServer() {
     'Create or update a record. If id is provided, updates that record. Otherwise inserts with dedup.',
     {
       id: z.number().int().optional().describe('Record ID to update (omit for new)'),
-      kind: z.enum(['issue', 'spec', 'arch', 'update']).describe('Record kind: issue (bug), spec (plan), arch (architecture decision), update (feature change)'),
+      kind: z.enum(['issue', 'spec', 'arch', 'update', 'test']).describe('Record kind: issue (bug), spec (plan), arch (architecture decision), update (feature change), test (verification procedure)'),
       title: z.string().describe('Short summary'),
       body: z.string().optional().describe('Full description'),
-      status: z.enum(['open', 'resolved', 'archived']).optional().describe('Defaults to open'),
+      status: z.enum(['open', 'resolved', 'archived', 'active', 'inactive']).optional().describe('Defaults to open. For tests: active = should be performed, inactive = disabled'),
     },
     async ({ id, kind, title, body, status }) => {
       try {
@@ -96,8 +96,8 @@ export async function startServer() {
     'list_records',
     'List records with optional filters.',
     {
-      kind: z.enum(['issue', 'spec', 'arch', 'update', 'all']).optional().describe('Filter by kind'),
-      status: z.enum(['open', 'resolved', 'archived', 'all']).optional().describe('Filter by status'),
+      kind: z.enum(['issue', 'spec', 'arch', 'update', 'test', 'all']).optional().describe('Filter by kind'),
+      status: z.enum(['open', 'resolved', 'archived', 'active', 'inactive', 'all']).optional().describe('Filter by status'),
       project: z.string().optional().describe('Project name, or "*" for all'),
     },
     async ({ kind, status, project }) => {
@@ -151,6 +151,31 @@ export async function startServer() {
     },
   );
 
+  // ---- sync_status ----
+  server.tool(
+    'sync_status',
+    'Check cloud sync status and optionally trigger a manual sync.',
+    {
+      trigger_sync: z.boolean().optional().describe('If true, trigger an immediate sync'),
+    },
+    async ({ trigger_sync }) => {
+      try {
+        const status = await db.syncStatus();
+        let result = { ...status };
+        if (trigger_sync && status.enabled) {
+          const syncResult = await db.sync();
+          result.sync = syncResult;
+        }
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        console.error('[dude] sync_status failed:', err);
+        return { content: [{ type: 'text', text: `Error in sync_status: ${err.message}` }], isError: true };
+      }
+    },
+  );
+
   // Start transport
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/web.js

@@ -61,6 +61,16 @@ async function handleRequest(db, req, res) {
 
   // --- API routes ---
 
+  // GET /api/sync-status
+  if (method === 'GET' && path === '/api/sync-status') {
+    return json(res, await db.syncStatus());
+  }
+
+  // POST /api/sync
+  if (method === 'POST' && path === '/api/sync') {
+    return json(res, await db.sync());
+  }
+
   // GET /api/projects
   if (method === 'GET' && path === '/api/projects') {
     return json(res, await db.listProjects());

package/web/index.html

@@ -56,9 +56,12 @@
     .badge-spec { background: #e3f2fd; color: #1565c0; }
     .badge-arch { background: #fff3e0; color: #e65100; }
     .badge-update { background: #e8f5e9; color: #1b5e20; }
+    .badge-test { background: #e0f7fa; color: #00695c; }
     .badge-open { background: #e8f5e9; color: #2e7d32; }
     .badge-resolved { background: #f3e5f5; color: #6a1b9a; }
     .badge-archived { background: #eceff1; color: #546e7a; }
+    .badge-active { background: #e8f5e9; color: #2e7d32; }
+    .badge-inactive { background: #fce4e4; color: #c62828; }
     .main-panel {
       flex: 1; padding: 24px; overflow-y: auto;
     }
@@ -114,12 +117,15 @@
           <option value="spec">Specs</option>
           <option value="arch">Arch</option>
           <option value="update">Updates</option>
+          <option value="test">Tests</option>
         </select>
         <select id="statusFilter">
           <option value="">All statuses</option>
           <option value="open">Open</option>
           <option value="resolved">Resolved</option>
           <option value="archived">Archived</option>
+          <option value="active">Active</option>
+          <option value="inactive">Inactive</option>
         </select>
         <button id="newBtn">+ New</button>
       </div>
@@ -214,6 +220,7 @@
             <option value="spec" ${record.kind === 'spec' ? 'selected' : ''}>Spec</option>
             <option value="arch" ${record.kind === 'arch' ? 'selected' : ''}>Arch</option>
             <option value="update" ${record.kind === 'update' ? 'selected' : ''}>Update</option>
+            <option value="test" ${record.kind === 'test' ? 'selected' : ''}>Test</option>
           </select>
         </div>
         <div class="form-group">
@@ -230,6 +237,8 @@
             <option value="open" ${record.status === 'open' ? 'selected' : ''}>Open</option>
             <option value="resolved" ${record.status === 'resolved' ? 'selected' : ''}>Resolved</option>
             <option value="archived" ${record.status === 'archived' ? 'selected' : ''}>Archived</option>
+            <option value="active" ${record.status === 'active' ? 'selected' : ''}>Active</option>
+            <option value="inactive" ${record.status === 'inactive' ? 'selected' : ''}>Inactive</option>
           </select>
         </div>
         <div class="btn-row">
@@ -254,6 +263,7 @@
             <option value="spec">Spec</option>
             <option value="arch">Arch</option>
             <option value="update">Update</option>
+            <option value="test">Test</option>
           </select>
         </div>
         <div class="form-group">
@@ -270,6 +280,8 @@
             <option value="open">Open</option>
             <option value="resolved">Resolved</option>
             <option value="archived">Archived</option>
+            <option value="active">Active</option>
+            <option value="inactive">Inactive</option>
           </select>
         </div>
         <div class="btn-row">