@aprovan/hardcopy 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+import { Database } from 'better-sqlite3';
+export { Database as BetterSqlite3Database } from 'better-sqlite3';
+import { LoroDoc } from 'loro-crdt';
+export { createMcpServer, serveMcp } from './mcp-server.js';
+import '@modelcontextprotocol/sdk/server/index.js';
+
+interface Node {
+    id: string;
+    type: string;
+    attrs: Record<string, unknown>;
+    syncedAt?: number;
+    versionToken?: string;
+    cursor?: string;
+}
+interface Edge {
+    id?: number;
+    type: string;
+    fromId: string;
+    toId: string;
+    attrs?: Record<string, unknown>;
+}
+interface FetchRequest {
+    query: NodeQuery;
+    cursor?: string;
+    pageSize?: number;
+    versionToken?: string;
+}
+interface FetchResult {
+    nodes: Node[];
+    edges: Edge[];
+    cursor?: string;
+    hasMore: boolean;
+    versionToken?: string | null;
+    cached?: boolean;
+}
+interface PushResult {
+    success: boolean;
+    error?: string;
+    versionToken?: string;
+}
+interface NodeQuery {
+    id?: string;
+    type?: string;
+    attrs?: Record<string, unknown>;
+}
+interface Change {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+interface SyncDecision {
+    strategy: "auto" | "llm" | "manual";
+    reason: string;
+}
+interface SyncError {
+    resourceId: string;
+    strategy: "auto" | "llm";
+    error: string;
+    llmExplanation?: string;
+    suggestedActions?: string[];
+}
+interface IndexState {
+    cursor?: string;
+    total?: number;
+    loaded: number;
+    pageSize: number;
+    lastFetch: string;
+    ttl: number;
+}
+declare enum ConflictStatus {
+    CLEAN = "clean",
+    REMOTE_ONLY = "remote",
+    DIVERGED = "diverged"
+}
+interface ThreeWayState {
+    base: unknown;
+    local: unknown;
+    remote: unknown;
+}
+interface FieldConflict {
+    field: string;
+    status: ConflictStatus;
+    base: unknown;
+    local: unknown;
+    remote: unknown;
+    canAutoMerge: boolean;
+}
+interface ConflictInfo {
+    nodeId: string;
+    nodeType: string;
+    filePath: string;
+    detectedAt: number;
+    fields: FieldConflict[];
+}
+
+interface Tool {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+interface Provider {
+    name: string;
+    nodeTypes: string[];
+    edgeTypes: string[];
+    fetch(request: FetchRequest): Promise<FetchResult>;
+    push(node: Node, changes: Change[]): Promise<PushResult>;
+    fetchNode(nodeId: string): Promise<Node | null>;
+    getTools(): Tool[];
+}
+type ProviderFactory = (config: Record<string, unknown>) => Provider;
+declare function registerProvider(name: string, factory: ProviderFactory): void;
+declare function getProvider(name: string): ProviderFactory | undefined;
+declare function listProviders(): string[];
+
+interface ParsedFile {
+    attrs: Record<string, unknown>;
+    body: string;
+}
+interface FormatHandler {
+    type: string;
+    editableFields: string[];
+    render(node: Node): string;
+    parse(content: string): ParsedFile;
+}
+declare function registerFormat(handler: FormatHandler): void;
+declare function getFormat(type: string): FormatHandler | undefined;
+declare function listFormats(): string[];
+declare function renderNode(node: Node, template?: string): string;
+declare function parseFile(content: string, type: string): ParsedFile;
+
+interface LinkConfig {
+    edge: string;
+    to: string;
+    match: string;
+}
+interface SourceConfig {
+    name: string;
+    provider: string;
+    orgs?: string[];
+    repositories?: {
+        path: string;
+    }[];
+    links?: LinkConfig[];
+    [key: string]: unknown;
+}
+interface RenderConfig {
+    path: string;
+    type?: string;
+    template?: string;
+    args?: Record<string, unknown>;
+}
+interface ViewConfig {
+    path: string;
+    description?: string;
+    query: string;
+    partition?: {
+        by: string;
+        fallback?: string;
+    };
+    render: RenderConfig[];
+}
+interface Config {
+    sources: SourceConfig[];
+    views: ViewConfig[];
+}
+declare function loadConfig(path: string): Promise<Config>;
+declare function parseConfig(content: string): Config;
+
+declare class HardcopyDatabase {
+    private db;
+    private graphqliteLoaded;
+    constructor(db: Database);
+    static open(path: string): Promise<HardcopyDatabase>;
+    private initialize;
+    private migrateLegacySchema;
+    private getTableColumns;
+    private renameTableIfNeeded;
+    private dropLegacyIndexes;
+    private resolveGraphqliteLoadPath;
+    private getExtensionCandidates;
+    private ensureGraphqliteLoaded;
+    private normalizeCypher;
+    private escapeCypherType;
+    private extractNodeIds;
+    private parseCypherRows;
+    cypher(query: string, params?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    queryViewNodes(query: string, params?: Record<string, unknown>): Promise<Node[]>;
+    getNodesByIds(ids: string[]): Promise<Node[]>;
+    upsertNode(node: Node): Promise<void>;
+    upsertNodes(nodes: Node[]): Promise<void>;
+    getNode(id: string): Promise<Node | null>;
+    queryNodes(type?: string): Promise<Node[]>;
+    deleteNode(id: string): Promise<void>;
+    upsertEdge(edge: Edge): Promise<void>;
+    upsertEdges(edges: Edge[]): Promise<void>;
+    getEdges(fromId?: string, toId?: string, type?: string): Promise<Edge[]>;
+    deleteEdge(fromId: string, toId: string, type: string): Promise<void>;
+    private escapeCypherString;
+    private upsertGraphNode;
+    private upsertGraphEdge;
+    private deleteGraphNode;
+    private deleteGraphEdge;
+    close(): Promise<void>;
+}
+
+declare class CRDTStore {
+    private basePath;
+    constructor(basePath: string);
+    private getPath;
+    exists(nodeId: string): Promise<boolean>;
+    load(nodeId: string): Promise<LoroDoc | null>;
+    save(nodeId: string, doc: LoroDoc): Promise<void>;
+    create(nodeId: string): Promise<LoroDoc>;
+    loadOrCreate(nodeId: string): Promise<LoroDoc>;
+    delete(nodeId: string): Promise<void>;
+    merge(nodeId: string, remote: LoroDoc): Promise<LoroDoc>;
+}
+declare function setDocContent(doc: LoroDoc, content: string): void;
+declare function getDocContent(doc: LoroDoc): string;
+declare function setDocAttrs(doc: LoroDoc, attrs: Record<string, unknown>): void;
+declare function getDocAttrs(doc: LoroDoc): Record<string, unknown>;
+
+interface HardcopyOptions {
+    root: string;
+}
+interface SyncStats {
+    nodes: number;
+    edges: number;
+    errors: string[];
+}
+interface StatusInfo {
+    totalNodes: number;
+    totalEdges: number;
+    nodesByType: Record<string, number>;
+    changedFiles: ChangedFile[];
+    conflicts: ConflictInfo[];
+}
+interface ChangedFile {
+    path: string;
+    fullPath: string;
+    nodeId: string;
+    nodeType: string;
+    status: "new" | "modified" | "deleted";
+    mtime: number;
+    syncedAt: number;
+}
+interface RefreshResult {
+    rendered: number;
+    orphaned: string[];
+    cleaned: boolean;
+}
+interface DiffResult {
+    nodeId: string;
+    nodeType: string;
+    filePath: string;
+    changes: Change[];
+}
+interface PushStats {
+    pushed: number;
+    skipped: number;
+    conflicts: number;
+    errors: string[];
+}
+
+interface GitHubConfig {
+    orgs?: string[];
+    repos?: string[];
+    token?: string;
+}
+declare function createGitHubProvider(config: GitHubConfig): Provider;
+
+interface A2AConfig {
+    endpoint?: string;
+    links?: {
+        edge: string;
+        to: string;
+        match: string;
+    }[];
+}
+declare function createA2AProvider(config: A2AConfig): Provider;
+
+interface GitConfig {
+    repositories?: {
+        path: string;
+    }[];
+    links?: {
+        edge: string;
+        to: string;
+        match: string;
+    }[];
+}
+declare function createGitProvider(config: GitConfig): Provider;
+
+declare class ConflictStore {
+    private conflictsDir;
+    constructor(conflictsDir: string);
+    save(info: ConflictInfo): Promise<void>;
+    list(): Promise<ConflictInfo[]>;
+    get(nodeId: string): Promise<ConflictInfo | null>;
+    read(nodeId: string): Promise<{
+        info: ConflictInfo;
+        body: string;
+    } | null>;
+    remove(nodeId: string): Promise<void>;
+    private getPath;
+    getArtifactPath(nodeId: string): string;
+}
+
+declare class Hardcopy {
+    readonly root: string;
+    readonly dataDir: string;
+    private _db;
+    private _crdt;
+    private _config;
+    private _providers;
+    private _conflictStore;
+    constructor(options: HardcopyOptions);
+    initialize(): Promise<void>;
+    loadConfig(): Promise<Config>;
+    private initializeProviders;
+    getDatabase(): HardcopyDatabase;
+    getCRDTStore(): CRDTStore;
+    getConflictStore(): ConflictStore;
+    getProviders(): Map<string, Provider>;
+    close(): Promise<void>;
+}
+
+declare function initHardcopy(root: string): Promise<void>;
+
+declare module "./core" {
+    interface Hardcopy {
+        sync(): Promise<SyncStats>;
+        getViews(): Promise<string[]>;
+        refreshView(viewPath: string, options?: {
+            clean?: boolean;
+        }): Promise<RefreshResult>;
+        diff(pattern?: string, options?: {
+            smart?: boolean;
+        }): Promise<DiffResult[]>;
+        getChangedFiles(pattern?: string): Promise<ChangedFile[]>;
+        push(filePath?: string, options?: {
+            force?: boolean;
+        }): Promise<PushStats>;
+        status(): Promise<StatusInfo>;
+        listConflicts(): Promise<ConflictInfo[]>;
+        getConflict(nodeId: string): Promise<ConflictInfo | null>;
+        getConflictDetail(nodeId: string): Promise<{
+            info: ConflictInfo;
+            body: string;
+            artifactPath: string;
+        } | null>;
+        resolveConflict(nodeId: string, resolution: Record<string, "local" | "remote">): Promise<void>;
+    }
+}
+
+declare function detectFieldConflict(field: string, state: ThreeWayState): FieldConflict;
+declare function detectConflicts(baseNode: Node, localParsed: ParsedFile, remoteNode: Node, editableFields: string[]): FieldConflict[];
+declare function hasUnresolvableConflicts(conflicts: FieldConflict[]): boolean;
+declare function autoMergeField(conflict: FieldConflict): unknown | null;
+declare function generateConflictMarkers(conflict: FieldConflict): string;
+declare function parseConflictMarkers(text: string): {
+    local: string;
+    base: string;
+    remote: string;
+} | null;
+
+/**
+ * LLM-based merge for conflicts that can't be auto-resolved.
+ *
+ * Uses an OpenAI-compatible endpoint (e.g., copilot-proxy) to intelligently
+ * merge conflicting changes by understanding semantic intent.
+ */
+interface LLMMergeOptions {
+    /** OpenAI-compatible API base URL (default: OPENAI_BASE_URL or http://localhost:6433) */
+    baseURL?: string;
+    /** Model to use (default: OPENAI_MODEL or gpt-4o) */
+    model?: string;
+    /** API key for authentication (default: OPENAI_API_KEY) */
+    apiKey?: string;
+    /** Temperature for generation (default: 0) */
+    temperature?: number;
+}
+/**
+ * Attempts to merge conflicting text using an LLM.
+ *
+ * @param base - The common ancestor text
+ * @param local - The local (your) version
+ * @param remote - The remote (their) version
+ * @param options - LLM configuration options
+ * @returns The merged text, or null if the LLM call fails
+ */
+declare function llmMergeText(base: string, local: string, remote: string, options?: LLMMergeOptions): Promise<string | null>;
+
+interface SemanticMergeOptions {
+    tempDir?: string;
+    filePath: string;
+    /** LLM merge options (URL, model, etc.) */
+    llmOptions?: LLMMergeOptions;
+}
+/**
+ * Attempts a 3-way merge using diff3, with LLM fallback for conflicts.
+ * Returns the merged text if successful, or null if merge fails entirely.
+ */
+declare function mergeText(base: string, local: string, remote: string, options: SemanticMergeOptions): Promise<string | null>;
+
+export { CRDTStore, type Change, type ChangedFile, type Config, type ConflictInfo, ConflictStatus, ConflictStore, HardcopyDatabase as Database, type DiffResult, type Edge, type FetchRequest, type FetchResult, type FieldConflict, type FormatHandler, Hardcopy, HardcopyDatabase, type HardcopyOptions, type IndexState, type LLMMergeOptions, type LinkConfig, type Node, type NodeQuery, type ParsedFile, type Provider, type ProviderFactory, type PushResult, type PushStats, type RefreshResult, type RenderConfig, type SemanticMergeOptions, type SourceConfig, type StatusInfo, type SyncDecision, type SyncError, type SyncStats, type ThreeWayState, type Tool, type ViewConfig, autoMergeField, createA2AProvider, createGitHubProvider, createGitProvider, detectConflicts, detectFieldConflict, generateConflictMarkers, getDocAttrs, getDocContent, getFormat, getProvider, hasUnresolvableConflicts, initHardcopy, listFormats, listProviders, llmMergeText, loadConfig, mergeText, parseConfig, parseConflictMarkers, parseFile, registerFormat, registerProvider, renderNode, setDocAttrs, setDocContent };