autosnippet/dist/lib/repository/remote/RemoteCommandRepository.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * RemoteCommandRepository — 远程指令队列 + 状态持久化 (Drizzle ORM)
 *
 * 封装 remote_commands 和 remote_state 两张表的所有数据访问，
 * 替代 remote.ts 路由中散落的 18+ 条内联 SQL。
 *
 * Drizzle 迁移策略：
 * - INSERT / UPDATE / SELECT 使用 drizzle 类型安全 API
 * - 简单聚合使用 drizzle sql`` 表达式
 * - 保留 raw prepared statements 用于有性能要求的高频定时器查询
 *
 * @module repository/remote/RemoteCommandRepository
 */
import type { Database } from 'better-sqlite3';
import type { DrizzleDB } from '../../infrastructure/database/drizzle/index.js';
/** Remote command row shape (from Drizzle select) */
export interface RemoteCommandRow {
    id: string;
    source: string;
    chatId: string | null;
    messageId: string | null;
    userId: string | null;
    userName: string | null;
    command: string;
    status: string;
    result: string | null;
    createdAt: number;
    claimedAt: number | null;
    completedAt: number | null;
}
/** Input for creating a new remote command */
export interface CreateCommandInput {
    id: string;
    source: string;
    chatId?: string;
    messageId?: string;
    userId?: string;
    userName?: string;
    command: string;
}
/** Status counts for queue diagnostics */
export interface StatusCounts {
    pending: number;
    running: number;
    completed: number;
    timeout: number;
}
export declare class RemoteCommandRepository {
    #private;
    constructor(db: Database, drizzle?: DrizzleDB);
    /** 写入新的远程指令到队列 */
    enqueue(input: CreateCommandInput): void;
    /**
     * 认领一条 pending 指令（CAS: pending → running）
     * @returns 是否成功（0 changes = 已被认领或不存在）
     */
    claim(id: string): boolean;
    /** 提交指令执行结果（running → completed/failed/...） */
    complete(id: string, resultText: string, status?: string): void;
    /**
     * 批量取消所有 pending 指令（IDE 重连时 flush）
     * @returns 被取消的指令列表
     */
    flushPending(): Array<{
        id: string;
        command: string;
        createdAt: number;
    }>;
    /** 获取最早的一条 pending 指令 */
    findFirstPending(): RemoteCommandRow | null;
    /** 根据 ID 获取指令 */
    findById(id: string): RemoteCommandRow | null;
    /** 获取历史记录（按创建时间降序） */
    getHistory(limit?: number): RemoteCommandRow[];
    /** 获取各状态的指令计数（用于 /lark/status 诊断面板） */
    getStatusCounts(): StatusCounts;
    /** 查找最近一次 claim 记录（用于 IDE 心跳检测） */
    findRecentClaim(): {
        claimedAt: number;
    } | null;
    /** 查找最近有 chatId 的指令（用于恢复活跃会话） */
    findRecentChatId(): string | null;
    /**
     * 清理超时的 pending 和 running 指令
     * @param pendingTimeoutSec pending 状态超时秒数
     * @param runningTimeoutSec running 状态超时秒数
     * @returns 清理的总条数
     */
    cleanupTimeouts(pendingTimeoutSec: number, runningTimeoutSec: number): number;
    /** 持久化键值对到 remote_state */
    setState(key: string, value: string): void;
    /** 从 remote_state 读取值 */
    getState(key: string): string | null;
}