@c3-oss/prosa 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+import { Database } from 'better-sqlite3';
+
+type Db = Database;
+
+interface BundleManifest {
+    version: 1;
+    parser_version: string;
+    schema_version: number;
+    created_at: string;
+    hash_alg: 'blake3';
+    default_compression: 'zstd';
+}
+interface Bundle {
+    path: string;
+    db: Db;
+    manifest: BundleManifest;
+    paths: {
+        db: string;
+        manifest: string;
+        objects: string;
+        rawSources: string;
+        search: string;
+        tantivy: string;
+        exports: string;
+        parquet: string;
+        lock: string;
+    };
+}
+declare function defaultBundlePath(): string;
+/**
+ * Create a fresh bundle at `rootPath`. Fails if the directory already contains
+ * a manifest (use openBundle for that case).
+ */
+declare function initBundle(rootPath: string): Promise<Bundle>;
+/**
+ * Open an existing bundle. Applies pending migrations if the schema is older
+ * than the current code expects.
+ */
+declare function openBundle(rootPath: string): Promise<Bundle>;
+declare function closeBundle(bundle: Bundle): void;
+
+declare function runMigrations(db: Db): {
+    applied: number[];
+};
+declare function currentSchemaVersion(db: Db): number;
+
+declare const PROSA_PARSER_VERSION = "0.1.0";
+declare const PROSA_SCHEMA_VERSION = 2;
+
+type Compression = 'zstd' | 'none';
+
+type ObjectId = string;
+interface ObjectMeta {
+    object_id: ObjectId;
+    hash_alg: 'blake3';
+    hash: string;
+    size_bytes: number;
+    compressed_size_bytes: number | null;
+    compression: Compression;
+    mime_type: string | null;
+    encoding: string | null;
+    storage_path: string;
+    created_at: string;
+}
+interface PutOptions {
+    mimeType?: string;
+    encoding?: string;
+}
+/**
+ * Store raw bytes in the CAS. Returns the object_id. Idempotent: if the same
+ * content already exists, returns the existing object_id without rewriting.
+ *
+ * Bytes are compressed with zstd when worth it (see compress.ts threshold).
+ * The on-disk path is `<bundle>/objects/blake3/ab/cd/<hash>.zst`.
+ */
+declare function putBytes(bundle: Bundle, bytes: Uint8Array, options?: PutOptions): Promise<ObjectId>;
+declare function putText(bundle: Bundle, text: string, options?: {
+    mimeType?: string;
+}): Promise<ObjectId>;
+declare function putJson(bundle: Bundle, value: unknown): Promise<ObjectId>;
+declare function getBytes(bundle: Bundle, objectId: ObjectId): Promise<Buffer>;
+declare function getText(bundle: Bundle, objectId: ObjectId): Promise<string>;
+declare function getJson<T = unknown>(bundle: Bundle, objectId: ObjectId): Promise<T>;
+declare function getObjectMeta(bundle: Bundle, objectId: ObjectId): ObjectMeta | null;
+
+type SourceTool = 'cursor' | 'codex' | 'claude' | 'gemini';
+type Confidence = 'high' | 'medium' | 'low';
+type MessageRole = 'system_prompt' | 'developer' | 'user' | 'assistant' | 'tool' | 'operational';
+type CanonicalToolType = 'shell' | 'read_file' | 'write_file' | 'edit_file' | 'search_file' | 'web_search' | 'mcp' | 'subagent' | 'patch' | 'other';
+type EdgeType = 'parent_of' | 'calls' | 'returns' | 'spawned' | 'contains' | 'produced' | 'consumed' | 'derived_from' | 'summarizes' | 'compacts' | 'same_as' | 'refers_to';
+type ToolCallStatus = 'started' | 'success' | 'error' | 'cancelled' | 'unknown';
+interface SessionRowFull {
+    session_id: string;
+    source_tool: SourceTool;
+    source_session_id: string;
+    project_id: string | null;
+    parent_session_id: string | null;
+    is_subagent: 0 | 1;
+    agent_role: string | null;
+    agent_nickname: string | null;
+    title: string | null;
+    summary: string | null;
+    start_ts: string | null;
+    end_ts: string | null;
+    cwd_initial: string | null;
+    git_branch_initial: string | null;
+    model_first: string | null;
+    model_last: string | null;
+    status: string | null;
+    timeline_confidence: Confidence;
+    raw_record_id: string | null;
+}
+
+interface ImportBatch {
+    batch_id: string;
+    source_tool: SourceTool | null;
+    parser_version: string;
+    paths: string[];
+    started_at: string;
+    finished_at?: string;
+}
+interface ImportCounts {
+    source_files_seen: number;
+    source_files_imported: number;
+    source_files_skipped: number;
+    raw_records: number;
+    sessions: number;
+    turns: number;
+    events: number;
+    messages: number;
+    content_blocks: number;
+    tool_calls: number;
+    tool_results: number;
+    artifacts: number;
+    edges: number;
+    errors: number;
+}
+declare function emptyCounts(): ImportCounts;
+declare function startBatch(bundle: Bundle, sourceTool: SourceTool | null, paths: string[]): ImportBatch;
+declare function finishBatch(bundle: Bundle, batch: ImportBatch, counts: ImportCounts, status: 'completed' | 'failed'): void;
+declare function recordError(bundle: Bundle, batchId: string, args: {
+    sourceFileId?: string | null;
+    rawRecordId?: string | null;
+    kind: string;
+    message: string;
+    payload?: unknown;
+}): Promise<void>;
+
+interface SourceFileRow {
+    source_file_id: string;
+    source_tool: SourceTool;
+    path: string;
+    file_kind: string;
+    size_bytes: number;
+    mtime: string | null;
+    content_hash: string;
+    object_id: string | null;
+    discovered_at: string;
+    workspace_hint: string | null;
+}
+interface RegisterResult {
+    row: SourceFileRow;
+    alreadyKnown: boolean;
+}
+/**
+ * Idempotent registration of a source file. The natural key is
+ * (source_tool, path, size, mtime, content_hash). If a row with the same
+ * tuple already exists we return it untouched and the caller can skip
+ * re-importing. Otherwise we insert a new row.
+ *
+ * This is the cheapest form of idempotency: re-running `prosa compile` over
+ * the same Codex tree is a no-op (no rehash unless the file changed).
+ */
+declare function registerSourceFile(bundle: Bundle, args: {
+    sourceTool: SourceTool;
+    absolutePath: string;
+    fileKind: string;
+    workspaceHint?: string | null;
+}): Promise<RegisterResult>;
+
+interface SessionListFilters {
+    sourceTool?: SourceTool;
+    sinceIso?: string;
+    untilIso?: string;
+    limit?: number;
+}
+interface SessionRow {
+    session_id: string;
+    source_tool: SourceTool;
+    source_session_id: string;
+    parent_session_id: string | null;
+    is_subagent: 0 | 1;
+    title: string | null;
+    start_ts: string | null;
+    end_ts: string | null;
+    cwd_initial: string | null;
+    git_branch_initial: string | null;
+    model_first: string | null;
+    model_last: string | null;
+    status: string | null;
+    timeline_confidence: Confidence;
+    message_count: number;
+    tool_call_count: number;
+}
+declare function listSessions(bundle: Bundle, filters?: SessionListFilters): SessionRow[];
+declare function countSessions(bundle: Bundle, filters?: SessionListFilters): number;
+interface SessionDetailEvent {
+    ordinal: number;
+    timestamp: string | null;
+    event_type: string;
+    source_type: string | null;
+    subtype: string | null;
+    actor: string | null;
+    message_id: string | null;
+    role: string | null;
+    tool_name: string | null;
+    is_error: 0 | 1 | null;
+    preview: string | null;
+}
+interface SessionDetail {
+    session: SessionRow;
+    events: SessionDetailEvent[];
+}
+declare function getSession(bundle: Bundle, sessionId: string): SessionDetail | null;
+
+type SearchEngine = 'fts5' | 'tantivy';
+interface SearchIndexStatus {
+    engine: SearchEngine;
+    status: 'missing' | 'ready' | 'stale' | 'building' | 'failed';
+    source_doc_count: number;
+    indexed_doc_count: number;
+    updated_at: string;
+    error_message: string | null;
+}
+declare function enableFts5Triggers(bundle: Bundle): void;
+declare function disableFts5Triggers(bundle: Bundle): void;
+declare function getSearchIndexStatuses(bundle: Bundle): SearchIndexStatus[];
+declare function getSearchIndexStatus(bundle: Bundle, engine: SearchEngine): SearchIndexStatus | null;
+declare function markIndexesAfterImport(bundle: Bundle, options: {
+    changed: boolean;
+    fts5Deferred: boolean;
+}): void;
+declare function rebuildFts5Index(bundle: Bundle): SearchIndexStatus;
+declare function rebuildTantivyIndex(bundle: Bundle): Promise<SearchIndexStatus>;
+
+interface SearchHit {
+    doc_id: string;
+    entity_type: string;
+    entity_id: string;
+    session_id: string | null;
+    timestamp: string | null;
+    role: string | null;
+    tool_name: string | null;
+    field_kind: string;
+    snippet: string;
+}
+interface SearchOptions {
+    query: string;
+    limit?: number;
+    engine?: SearchEngine;
+    /**
+     * When true, pass `query` straight to FTS5 (MATCH expression). When false
+     * (default), each whitespace-delimited token is wrapped in double quotes so
+     * punctuation like `package.json` doesn't trip the FTS5 parser. Set true if
+     * you want to use FTS5 operators like `OR`, `NEAR`, prefixes, etc.
+     */
+    raw?: boolean;
+}
+/**
+ * FTS5 search over messages, tool calls and tool outputs. Caller passes a
+ * raw FTS5 MATCH query. We project a snippet around the hit and join with
+ * search_docs to recover entity metadata.
+ */
+declare function searchFullText(bundle: Bundle, options: SearchOptions): SearchHit[];
+
+/**
+ * Render a session into Markdown. Big tool outputs aren't dumped inline:
+ * we show a preview line plus a `[object: blake3:…]` reference, leaving the
+ * raw bytes in the CAS for downstream tools.
+ */
+declare function exportSessionMarkdown(bundle: Bundle, sessionId: string): Promise<string>;
+
+declare const PARQUET_TABLES: readonly ["objects", "source_files", "import_batches", "raw_records", "import_errors", "uncertainties", "projects", "sessions", "turns", "events", "messages", "content_blocks", "tool_calls", "tool_results", "artifacts", "edges", "search_docs"];
+type ParquetTable = (typeof PARQUET_TABLES)[number];
+interface ParquetExportOptions {
+    bundlePath: string;
+    outDir?: string;
+}
+interface ParquetExportResult {
+    outDir: string;
+    manifestPath: string;
+    files: Record<ParquetTable, string>;
+    counts: Record<ParquetTable, number>;
+}
+interface DuckDbQueryOptions {
+    parquetDir: string;
+    sql: string;
+}
+interface DuckDbQueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+}
+declare function exportBundleParquet(options: ParquetExportOptions): Promise<ParquetExportResult>;
+declare function queryDuckDbParquet(options: DuckDbQueryOptions): Promise<DuckDbQueryResult>;
+
+interface CompileResult$3 {
+    batch: ImportBatch;
+    counts: ImportCounts;
+}
+declare function compileCodex(bundle: Bundle, root: string): Promise<CompileResult$3>;
+
+interface CompileResult$2 {
+    batch: ImportBatch;
+    counts: ImportCounts;
+}
+declare function compileClaude(bundle: Bundle, root: string): Promise<CompileResult$2>;
+
+interface CompileResult$1 {
+    batch: ImportBatch;
+    counts: ImportCounts;
+}
+declare function compileGemini(bundle: Bundle, root: string): Promise<CompileResult$1>;
+
+interface CompileResult {
+    batch: ImportBatch;
+    counts: ImportCounts;
+}
+declare function compileCursor(bundle: Bundle, root: string): Promise<CompileResult>;
+
+export { type Bundle, type BundleManifest, type CanonicalToolType, type CompileResult$2 as ClaudeCompileResult, type CompileResult$3 as CodexCompileResult, type Confidence, type CompileResult as CursorCompileResult, type DuckDbQueryOptions, type DuckDbQueryResult, type EdgeType, type CompileResult$1 as GeminiCompileResult, type ImportBatch, type ImportCounts, type MessageRole, type ObjectId, type ObjectMeta, PARQUET_TABLES, PROSA_PARSER_VERSION, PROSA_SCHEMA_VERSION, type ParquetExportOptions, type ParquetExportResult, type ParquetTable, type RegisterResult, type SearchEngine, type SearchHit, type SearchIndexStatus, type SearchOptions, type SessionDetail, type SessionDetailEvent, type SessionListFilters, type SessionRow, type SessionRowFull, type SourceFileRow, type SourceTool, type ToolCallStatus, closeBundle, compileClaude, compileCodex, compileCursor, compileGemini, countSessions, currentSchemaVersion, defaultBundlePath, disableFts5Triggers, emptyCounts, enableFts5Triggers, exportBundleParquet, exportSessionMarkdown, finishBatch, getBytes, getJson, getObjectMeta, getSearchIndexStatus, getSearchIndexStatuses, getSession, getText, initBundle, listSessions, markIndexesAfterImport, openBundle, putBytes, putJson, putText, queryDuckDbParquet, rebuildFts5Index, rebuildTantivyIndex, recordError, registerSourceFile, runMigrations, searchFullText, startBatch };