@cleocode/core 2026.4.9 → 2026.4.11

package/dist/store/agent-registry-accessor.js

@@ -0,0 +1,265 @@
+/**
+ * Agent Registry Accessor — CRUD operations for agent data in signaldock.db.
+ *
+ * signaldock.db is the SSoT for ALL agent data: identity, credentials,
+ * capabilities, skills, transport config. No agent data lives in tasks.db.
+ *
+ * API keys are encrypted at rest using the crypto/credentials module.
+ *
+ * @see docs/specs/DATABASE-ARCHITECTURE.md
+ * @task T234
+ */
+import { createRequire } from 'node:module';
+import { decrypt, encrypt } from '../crypto/credentials.js';
+import { ensureSignaldockDb, getSignaldockDbPath } from './signaldock-sqlite.js';
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite');
+/** Convert a signaldock.db row to an AgentCredential, decrypting the API key. */
+async function rowToCredential(row, projectPath) {
+    const apiKey = row.api_key_encrypted ? await decrypt(row.api_key_encrypted, projectPath) : '';
+    return {
+        agentId: row.agent_id,
+        displayName: row.name,
+        apiKey,
+        apiBaseUrl: row.api_base_url,
+        classification: row.classification ?? undefined,
+        privacyTier: row.privacy_tier,
+        capabilities: JSON.parse(row.capabilities),
+        skills: JSON.parse(row.skills),
+        transportType: (row.transport_type ?? 'http'),
+        transportConfig: JSON.parse(row.transport_config),
+        isActive: row.is_active === 1,
+        lastUsedAt: row.last_used_at ? new Date(row.last_used_at * 1000).toISOString() : undefined,
+        createdAt: new Date(row.created_at * 1000).toISOString(),
+        updatedAt: new Date(row.updated_at * 1000).toISOString(),
+    };
+}
+/** Open signaldock.db for read/write operations. Caller must close. */
+function openDb(projectPath) {
+    const dbPath = getSignaldockDbPath(projectPath);
+    const db = new DatabaseSyncClass(dbPath);
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA journal_mode = WAL');
+    return db;
+}
+/**
+ * Sync capabilities/skills to junction tables in signaldock.db.
+ * Junction tables are the SSoT — JSON columns are materialized cache.
+ */
+function syncJunctionTables(db, agentUuid, capabilities, skills) {
+    db.prepare('DELETE FROM agent_capabilities WHERE agent_id = ?').run(agentUuid);
+    db.prepare('DELETE FROM agent_skills WHERE agent_id = ?').run(agentUuid);
+    for (const cap of capabilities) {
+        const capRow = db.prepare('SELECT id FROM capabilities WHERE slug = ?').get(cap);
+        if (capRow) {
+            db.prepare('INSERT OR IGNORE INTO agent_capabilities (agent_id, capability_id) VALUES (?, ?)').run(agentUuid, capRow.id);
+        }
+    }
+    for (const skill of skills) {
+        const skillRow = db.prepare('SELECT id FROM skills WHERE slug = ?').get(skill);
+        if (skillRow) {
+            db.prepare('INSERT OR IGNORE INTO agent_skills (agent_id, skill_id) VALUES (?, ?)').run(agentUuid, skillRow.id);
+        }
+    }
+}
+/** signaldock.db implementation of the AgentRegistryAPI. */
+export class AgentRegistryAccessor {
+    projectPath;
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+    }
+    /** Ensure signaldock.db exists with full schema before any operation. */
+    async ensureDb() {
+        await ensureSignaldockDb(this.projectPath);
+    }
+    async register(credential) {
+        await this.ensureDb();
+        const nowTs = Math.floor(Date.now() / 1000);
+        const apiKeyEncrypted = credential.apiKey
+            ? await encrypt(credential.apiKey, this.projectPath)
+            : null;
+        const db = openDb(this.projectPath);
+        try {
+            const existing = db
+                .prepare('SELECT id FROM agents WHERE agent_id = ?')
+                .get(credential.agentId);
+            if (!existing) {
+                const id = crypto.randomUUID();
+                db.prepare(`INSERT INTO agents (id, agent_id, name, class, privacy_tier, capabilities, skills,
+           transport_type, api_key_encrypted, api_base_url, classification, transport_config,
+           is_active, last_used_at, status, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'online', ?, ?)`).run(id, credential.agentId, credential.displayName, credential.classification ?? 'custom', credential.privacyTier, JSON.stringify(credential.capabilities), JSON.stringify(credential.skills), credential.transportType ?? 'http', apiKeyEncrypted, credential.apiBaseUrl, credential.classification ?? null, JSON.stringify(credential.transportConfig), credential.isActive ? 1 : 0, credential.lastUsedAt
+                    ? Math.floor(new Date(credential.lastUsedAt).getTime() / 1000)
+                    : null, nowTs, nowTs);
+                syncJunctionTables(db, id, credential.capabilities, credential.skills);
+            }
+            else {
+                db.prepare(`UPDATE agents SET name = ?, class = ?, privacy_tier = ?, capabilities = ?, skills = ?,
+           transport_type = ?, api_key_encrypted = ?, api_base_url = ?, classification = ?,
+           transport_config = ?, is_active = ?, updated_at = ? WHERE agent_id = ?`).run(credential.displayName, credential.classification ?? 'custom', credential.privacyTier, JSON.stringify(credential.capabilities), JSON.stringify(credential.skills), credential.transportType ?? 'http', apiKeyEncrypted, credential.apiBaseUrl, credential.classification ?? null, JSON.stringify(credential.transportConfig), credential.isActive ? 1 : 0, nowTs, credential.agentId);
+                syncJunctionTables(db, existing.id, credential.capabilities, credential.skills);
+            }
+        }
+        finally {
+            db.close();
+        }
+        const result = await this.get(credential.agentId);
+        if (!result)
+            throw new Error(`Failed to register agent: ${credential.agentId}`);
+        return result;
+    }
+    async get(agentId) {
+        await this.ensureDb();
+        const db = openDb(this.projectPath);
+        try {
+            const row = db.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId);
+            if (!row)
+                return null;
+            return rowToCredential(row, this.projectPath);
+        }
+        finally {
+            db.close();
+        }
+    }
+    async list(filter) {
+        await this.ensureDb();
+        const db = openDb(this.projectPath);
+        try {
+            const rows = filter?.active !== undefined
+                ? db
+                    .prepare('SELECT * FROM agents WHERE is_active = ?')
+                    .all(filter.active ? 1 : 0)
+                : db.prepare('SELECT * FROM agents').all();
+            return Promise.all(rows.map((row) => rowToCredential(row, this.projectPath)));
+        }
+        finally {
+            db.close();
+        }
+    }
+    async update(agentId, updates) {
+        const existing = await this.get(agentId);
+        if (!existing)
+            throw new Error(`Agent not found: ${agentId}`);
+        const nowTs = Math.floor(Date.now() / 1000);
+        const db = openDb(this.projectPath);
+        try {
+            const sets = ['updated_at = ?'];
+            const params = [nowTs];
+            if (updates.displayName !== undefined) {
+                sets.push('name = ?');
+                params.push(updates.displayName);
+            }
+            if (updates.apiBaseUrl !== undefined) {
+                sets.push('api_base_url = ?');
+                params.push(updates.apiBaseUrl);
+            }
+            if (updates.classification !== undefined) {
+                sets.push('classification = ?');
+                params.push(updates.classification);
+            }
+            if (updates.privacyTier !== undefined) {
+                sets.push('privacy_tier = ?');
+                params.push(updates.privacyTier);
+            }
+            if (updates.capabilities !== undefined) {
+                sets.push('capabilities = ?');
+                params.push(JSON.stringify(updates.capabilities));
+            }
+            if (updates.skills !== undefined) {
+                sets.push('skills = ?');
+                params.push(JSON.stringify(updates.skills));
+            }
+            if (updates.transportType !== undefined) {
+                sets.push('transport_type = ?');
+                params.push(updates.transportType);
+            }
+            if (updates.transportConfig !== undefined) {
+                sets.push('transport_config = ?');
+                params.push(JSON.stringify(updates.transportConfig));
+            }
+            if (updates.isActive !== undefined) {
+                sets.push('is_active = ?');
+                params.push(updates.isActive ? 1 : 0);
+            }
+            if (updates.apiKey !== undefined) {
+                const encrypted = await encrypt(updates.apiKey, this.projectPath);
+                sets.push('api_key_encrypted = ?');
+                params.push(encrypted);
+            }
+            params.push(agentId);
+            db.prepare(`UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`).run(...params);
+            // Sync junction tables if capabilities or skills changed
+            if (updates.capabilities !== undefined || updates.skills !== undefined) {
+                const agentRow = db.prepare('SELECT id FROM agents WHERE agent_id = ?').get(agentId);
+                syncJunctionTables(db, agentRow.id, updates.capabilities ?? existing.capabilities, updates.skills ?? existing.skills);
+            }
+        }
+        finally {
+            db.close();
+        }
+        const result = await this.get(agentId);
+        if (!result)
+            throw new Error(`Agent not found after update: ${agentId}`);
+        return result;
+    }
+    async remove(agentId) {
+        const existing = await this.get(agentId);
+        if (!existing)
+            throw new Error(`Agent not found: ${agentId}`);
+        const db = openDb(this.projectPath);
+        try {
+            db.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
+        }
+        finally {
+            db.close();
+        }
+    }
+    async rotateKey(agentId) {
+        const credential = await this.get(agentId);
+        if (!credential)
+            throw new Error(`Agent not found: ${agentId}`);
+        const response = await fetch(`${credential.apiBaseUrl}/agents/${agentId}/rotate-key`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${credential.apiKey}`,
+                'X-Agent-Id': agentId,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to rotate key on cloud: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        const newApiKey = data.data?.apiKey;
+        if (!newApiKey)
+            throw new Error('Cloud API did not return a new API key');
+        await this.update(agentId, { apiKey: newApiKey });
+        return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
+    }
+    async getActive() {
+        await this.ensureDb();
+        const db = openDb(this.projectPath);
+        try {
+            const row = db
+                .prepare('SELECT * FROM agents WHERE is_active = 1 ORDER BY last_used_at DESC, created_at DESC LIMIT 1')
+                .get();
+            if (!row)
+                return null;
+            return rowToCredential(row, this.projectPath);
+        }
+        finally {
+            db.close();
+        }
+    }
+    async markUsed(agentId) {
+        await this.ensureDb();
+        const nowTs = Math.floor(Date.now() / 1000);
+        const db = openDb(this.projectPath);
+        try {
+            db.prepare('UPDATE agents SET last_used_at = ?, updated_at = ? WHERE agent_id = ?').run(nowTs, nowTs, agentId);
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+//# sourceMappingURL=agent-registry-accessor.js.map

package/dist/store/agent-registry-accessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry-accessor.js","sourceRoot":"","sources":["../../src/store/agent-registry-accessor.ts"],"names":[],"mappings":"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"}

package/dist/store/atomic.js

@@ -0,0 +1,167 @@
+/**
+ * Atomic file write operations using write-file-atomic.
+ * Ensures writes are crash-safe: temp file -> validate -> rename.
+ * @epic T4454
+ * @task T4457
+ * @task T4721 - Added atomic database operations
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import writeFileAtomic from 'write-file-atomic';
+import { CleoError } from '../errors.js';
+/**
+ * Write data to a file atomically.
+ * Creates parent directories if they don't exist.
+ * Uses write-file-atomic for crash-safe writes (temp file -> rename).
+ */
+export async function atomicWrite(filePath, data, options) {
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFileAtomic(filePath, data, {
+            encoding: options?.encoding ?? 'utf8',
+            mode: options?.mode,
+        });
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.FILE_ERROR, `Atomic write failed: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Read a file and return its contents.
+ * Returns null if the file does not exist.
+ */
+export async function safeReadFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return null;
+        }
+        throw new CleoError(ExitCode.FILE_ERROR, `Failed to read: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Write JSON data atomically with consistent formatting.
+ */
+export async function atomicWriteJson(filePath, data, options) {
+    const json = JSON.stringify(data, null, options?.indent ?? 2) + '\n';
+    await atomicWrite(filePath, json);
+}
+/**
+ * Perform atomic database migration using rename operations.
+ *
+ * Pattern:
+ *   1. Write new database to temp file (tasks.db.new)
+ *   2. Validate temp database integrity
+ *   3. Rename existing tasks.db → tasks.db.backup
+ *   4. Rename temp → tasks.db (atomic)
+ *   5. Only delete backup on success
+ *
+ * @param dbPath - Path to the database file (e.g., tasks.db)
+ * @param tempPath - Path to temporary database (e.g., tasks.db.new)
+ * @param validateFn - Async function to validate the temp database
+ * @returns Result with paths and success status
+ */
+export async function atomicDatabaseMigration(dbPath, tempPath, validateFn) {
+    const backupPath = `${dbPath}.backup`;
+    try {
+        // Step 1: Validate temp database exists
+        if (!existsSync(tempPath)) {
+            throw new Error(`Temp database not found: ${tempPath}`);
+        }
+        // Step 2: Validate the temp database integrity
+        const isValid = await validateFn(tempPath);
+        if (!isValid) {
+            throw new Error(`Temp database validation failed: ${tempPath}`);
+        }
+        // Step 3: If existing database exists, rename to backup
+        if (existsSync(dbPath)) {
+            await rename(dbPath, backupPath);
+        }
+        // Step 4: Atomically rename temp to final (atomic on POSIX systems)
+        await rename(tempPath, dbPath);
+        return {
+            success: true,
+            tempPath,
+            backupPath: existsSync(backupPath) ? backupPath : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            tempPath,
+            backupPath: existsSync(backupPath) ? backupPath : undefined,
+            error: String(err),
+        };
+    }
+}
+/**
+ * Restore database from backup after failed migration.
+ *
+ * @param dbPath - Path to the database file
+ * @param backupPath - Path to the backup file
+ * @returns true if restore succeeded
+ */
+export async function restoreDatabaseFromBackup(dbPath, backupPath) {
+    try {
+        if (!existsSync(backupPath)) {
+            return false;
+        }
+        // If a partial database exists, remove it
+        if (existsSync(dbPath)) {
+            await unlink(dbPath);
+        }
+        // Restore from backup
+        await rename(backupPath, dbPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clean up migration artifacts after successful migration.
+ *
+ * @param backupPath - Path to backup file to delete
+ * @returns true if cleanup succeeded
+ */
+export async function cleanupMigrationArtifacts(backupPath) {
+    try {
+        if (existsSync(backupPath)) {
+            await unlink(backupPath);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate SQLite database integrity by attempting to open it.
+ *
+ * @param dbPath - Path to database file
+ * @returns true if database is valid
+ */
+export async function validateSqliteDatabase(dbPath) {
+    try {
+        const { createRequire } = await import('node:module');
+        const _req = createRequire(import.meta.url);
+        const { DatabaseSync } = _req('node:sqlite');
+        const db = new DatabaseSync(dbPath, { readOnly: true });
+        const integrityRow = db.prepare('PRAGMA integrity_check').get();
+        const isOk = integrityRow?.integrity_check === 'ok';
+        const tableRow = db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='tasks'")
+            .get();
+        const hasTasksTable = !!tableRow;
+        db.close();
+        return isOk && hasTasksTable;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=atomic.js.map

package/dist/store/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/store/atomic.ts"],"names":[],"mappings":"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"}

package/dist/store/backup.js

@@ -0,0 +1,94 @@
+/**
+ * Numbered backup system for CLEO data files.
+ * Maintains a rotating window of recent backups for rollback protection.
+ * @epic T4454
+ * @task T4457
+ */
+import { copyFile, rename as fsRename, mkdir, readdir, stat, unlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+const DEFAULT_MAX_BACKUPS = 5;
+/**
+ * Create a numbered backup of a file.
+ * Rotates existing backups (file.1 -> file.2, etc.) and removes excess.
+ */
+export async function createBackup(filePath, backupDir, maxBackups = DEFAULT_MAX_BACKUPS) {
+    try {
+        await mkdir(backupDir, { recursive: true });
+        const fileName = basename(filePath);
+        // Check if source file exists
+        try {
+            await stat(filePath);
+        }
+        catch {
+            throw new CleoError(ExitCode.FILE_ERROR, `Cannot backup: source file not found: ${filePath}`);
+        }
+        // Rotate existing backups (shift numbers up)
+        for (let i = maxBackups; i >= 1; i--) {
+            const current = join(backupDir, `${fileName}.${i}`);
+            if (i === maxBackups) {
+                // Remove oldest backup
+                try {
+                    await unlink(current);
+                }
+                catch {
+                    // File may not exist
+                }
+            }
+            else {
+                const next = join(backupDir, `${fileName}.${i + 1}`);
+                try {
+                    await stat(current);
+                    await fsRename(current, next);
+                }
+                catch {
+                    // File may not exist
+                }
+            }
+        }
+        // Create new backup as .1
+        const backupPath = join(backupDir, `${fileName}.1`);
+        await copyFile(filePath, backupPath);
+        return backupPath;
+    }
+    catch (err) {
+        if (err instanceof CleoError)
+            throw err;
+        throw new CleoError(ExitCode.FILE_ERROR, `Backup failed for: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * List existing backups for a file, sorted by number (newest first).
+ */
+export async function listBackups(fileName, backupDir) {
+    try {
+        const entries = await readdir(backupDir);
+        const prefix = `${fileName}.`;
+        return entries
+            .filter((e) => e.startsWith(prefix) && /^\d+$/.test(e.slice(prefix.length)))
+            .sort((a, b) => {
+            const numA = parseInt(a.slice(prefix.length), 10);
+            const numB = parseInt(b.slice(prefix.length), 10);
+            return numA - numB;
+        })
+            .map((e) => join(backupDir, e));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Restore a file from its most recent backup.
+ * Returns the path of the backup that was restored.
+ */
+export async function restoreFromBackup(fileName, backupDir, targetPath) {
+    const backups = await listBackups(fileName, backupDir);
+    if (backups.length === 0) {
+        throw new CleoError(ExitCode.NOT_FOUND, `No backups found for: ${fileName}`);
+    }
+    const newest = backups[0];
+    await copyFile(newest, targetPath);
+    return newest;
+}
+//# sourceMappingURL=backup.js.map

package/dist/store/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/store/backup.ts"],"names":[],"mappings":"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"}