@zewstid/zeye-capture 0.2.0

package/dist/src/fileOutbox.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileOutbox = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const canonical_1 = require("./canonical");
+const zeye_shared_1 = require("@zewstid/zeye-shared");
+const EMPTY_STATE = { version: 1, deliveries: {}, checkpoints: {} };
+class FileOutbox {
+    redactor;
+    statePath;
+    writeQueue = Promise.resolve();
+    constructor(directory, redactor) {
+        this.redactor = redactor;
+        this.statePath = (0, node_path_1.join)(directory, 'outbox-v1.json');
+    }
+    async enqueue(event, context) {
+        this.validateEvent(event);
+        const redacted = await this.redactor.redact(event);
+        // Parse and clone the context before it reaches durable storage. This keeps
+        // provider event IDs and the repository checkout facts in the same
+        // idempotency boundary without retaining a raw remote URL or local path.
+        const captureRepositories = context
+            ? zeye_shared_1.CaptureRepositoryReference.array().max(100).parse(context.repositories).map(repository => ({ ...repository }))
+            : undefined;
+        const sourceKey = this.sourceKey(event);
+        const payloadHash = (0, canonical_1.sha256)({
+            adapter: event.adapter,
+            sessionId: event.sessionId,
+            sourceEventId: event.sourceEventId,
+            ...(event.clientName ? { clientName: event.clientName } : {}),
+            ...(event.clientVersion ? { clientVersion: event.clientVersion } : {}),
+            ...(event.sourceGenerationId ? { sourceGenerationId: event.sourceGenerationId } : {}),
+            ...(event.relationship ? { relationship: event.relationship } : {}),
+            ...(event.relatedSourceSessionId ? { relatedSourceSessionId: event.relatedSourceSessionId } : {}),
+            type: event.type,
+            occurredAt: event.occurredAt,
+            ...(captureRepositories ? { captureRepositories } : {}),
+            payload: redacted.payload,
+            ...(redacted.transcript ? { transcript: redacted.transcript } : {}),
+        });
+        return this.update(async (state) => {
+            const existing = Object.values(state.deliveries).find(record => record.sourceKey === sourceKey || (event.deliveryId !== undefined && record.deliveryId === event.deliveryId));
+            if (existing) {
+                return {
+                    status: existing.payloadHash === payloadHash ? 'DUPLICATE' : 'CONFLICT',
+                    record: { ...existing, status: existing.payloadHash === payloadHash ? existing.status : 'CONFLICT' },
+                };
+            }
+            const now = new Date().toISOString();
+            const sequence = Object.values(state.deliveries)
+                .filter(record => record.adapter === event.adapter && record.sessionId === event.sessionId && record.sourceGenerationId === event.sourceGenerationId)
+                .reduce((highest, record) => Math.max(highest, record.sequence), -1) + 1;
+            const record = {
+                deliveryId: event.deliveryId ?? (0, canonical_1.newDeliveryId)(),
+                sourceKey,
+                adapter: event.adapter,
+                sessionId: event.sessionId,
+                sourceEventId: event.sourceEventId,
+                ...(event.clientName ? { clientName: event.clientName } : {}),
+                ...(event.clientVersion ? { clientVersion: event.clientVersion } : {}),
+                ...(event.sourceGenerationId ? { sourceGenerationId: event.sourceGenerationId } : {}),
+                relationship: event.relationship || 'ROOT',
+                ...(event.relatedSourceSessionId ? { relatedSourceSessionId: event.relatedSourceSessionId } : {}),
+                type: event.type,
+                sequence,
+                occurredAt: event.occurredAt,
+                ...(captureRepositories ? { captureRepositories } : {}),
+                payload: redacted.payload,
+                ...(redacted.transcript ? { transcript: redacted.transcript } : {}),
+                payloadHash,
+                redactionCount: redacted.redactionCount,
+                redactionReasons: redacted.redactionReasons ?? [],
+                status: 'PENDING',
+                attempts: 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+            state.deliveries[record.deliveryId] = record;
+            return { status: 'ENQUEUED', record: { ...record } };
+        });
+    }
+    async nextBatch(limit) {
+        if (!Number.isInteger(limit) || limit < 1)
+            throw new RangeError('limit must be a positive integer');
+        return this.read(state => Object.values(state.deliveries)
+            .filter(record => record.status === 'PENDING' || record.status === 'RETRY')
+            .sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+            .slice(0, limit)
+            .map(record => ({ ...record })));
+    }
+    async markAttempt(deliveryId, error) {
+        return this.update(async (state) => {
+            const record = this.requireDelivery(state, deliveryId);
+            if (record.status === 'ACKNOWLEDGED' || record.status === 'CONFLICT')
+                return { ...record };
+            record.attempts += 1;
+            record.lastAttemptAt = new Date().toISOString();
+            record.updatedAt = record.lastAttemptAt;
+            if (error) {
+                record.status = 'RETRY';
+                record.lastError = error;
+            }
+            else {
+                record.status = 'PENDING';
+                delete record.lastError;
+            }
+            return { ...record };
+        });
+    }
+    async acknowledge(deliveryId, receiptId) {
+        if (!receiptId.trim())
+            throw new Error('receiptId is required');
+        return this.update(async (state) => {
+            const record = this.requireDelivery(state, deliveryId);
+            if (record.status === 'CONFLICT')
+                throw new Error(`Cannot acknowledge conflicted delivery ${deliveryId}`);
+            if (record.status === 'ACKNOWLEDGED') {
+                if (record.receiptId !== receiptId)
+                    throw new Error(`Delivery ${deliveryId} was acknowledged with a different receipt`);
+                return { ...record };
+            }
+            const now = new Date().toISOString();
+            record.status = 'ACKNOWLEDGED';
+            record.receiptId = receiptId;
+            record.acknowledgedAt = now;
+            record.updatedAt = now;
+            delete record.lastError;
+            return { ...record };
+        });
+    }
+    async checkpoint(adapter, scope, cursor) {
+        if (!adapter.trim() || !scope.trim() || !cursor.trim())
+            throw new Error('adapter, scope, and cursor are required');
+        return this.update(async (state) => {
+            const checkpoint = { adapter, scope, cursor, updatedAt: new Date().toISOString() };
+            state.checkpoints[this.checkpointKey(adapter, scope)] = checkpoint;
+            return { ...checkpoint };
+        });
+    }
+    async getCheckpoint(adapter, scope) {
+        return this.read(state => {
+            const checkpoint = state.checkpoints[this.checkpointKey(adapter, scope)];
+            return checkpoint ? { ...checkpoint } : undefined;
+        });
+    }
+    async list() {
+        return this.read(state => Object.values(state.deliveries)
+            .sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+            .map(record => ({ ...record })));
+    }
+    async read(operation) {
+        await this.writeQueue;
+        return operation(await this.readState());
+    }
+    async update(operation) {
+        let result;
+        const operationQueue = this.writeQueue.then(async () => {
+            const state = await this.readState();
+            result = await operation(state);
+            await this.writeState(state);
+        });
+        // A rejected caller operation must not poison the outbox for subsequent
+        // hook events. The current caller still receives its original error.
+        this.writeQueue = operationQueue.catch(() => undefined);
+        await operationQueue;
+        return result;
+    }
+    async readState() {
+        try {
+            const content = await (0, promises_1.readFile)(this.statePath, 'utf8');
+            const parsed = JSON.parse(content);
+            if (parsed.version !== 1 || !parsed.deliveries || !parsed.checkpoints)
+                throw new Error('Unsupported or corrupt outbox state');
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return structuredClone(EMPTY_STATE);
+            throw error;
+        }
+    }
+    async writeState(state) {
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.statePath), { recursive: true, mode: 0o700 });
+        const temporaryPath = `${this.statePath}.${process.pid}.${Date.now()}.tmp`;
+        await (0, promises_1.writeFile)(temporaryPath, `${(0, canonical_1.canonicalJson)(state)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await (0, promises_1.rename)(temporaryPath, this.statePath);
+    }
+    sourceKey(event) {
+        return `${event.adapter}:${event.sessionId}:${event.sourceGenerationId || event.sessionId}:${event.sourceEventId}`;
+    }
+    checkpointKey(adapter, scope) {
+        return `${adapter}:${scope}`;
+    }
+    requireDelivery(state, deliveryId) {
+        const record = state.deliveries[deliveryId];
+        if (!record)
+            throw new Error(`Unknown delivery: ${deliveryId}`);
+        return record;
+    }
+    validateEvent(event) {
+        for (const [key, value] of Object.entries({
+            adapter: event.adapter,
+            sessionId: event.sessionId,
+            sourceEventId: event.sourceEventId,
+            occurredAt: event.occurredAt,
+            type: event.type,
+        })) {
+            if (!value?.trim())
+                throw new Error(`${key} is required`);
+        }
+        if (Number.isNaN(Date.parse(event.occurredAt)))
+            throw new Error('occurredAt must be an ISO-8601 timestamp');
+        if (event.relationship && event.relationship !== 'ROOT' && !event.relatedSourceSessionId?.trim()) {
+            throw new Error('relatedSourceSessionId is required for non-root session lineage');
+        }
+    }
+}
+exports.FileOutbox = FileOutbox;

package/dist/src/host.d.ts

@@ -0,0 +1,14 @@
+import { type CaptureTransportConfiguration } from './transport';
+import type { CaptureDeliveryContext, DurableOutbox } from './types';
+export interface CodexImportResult {
+    imported: number;
+    skipped: number;
+    deferred: number;
+    rotated: boolean;
+}
+/**
+ * Imports only unseen Codex JSONL lines. A file truncation/reset is treated as
+ * a new source generation rather than silently skipping fresh evidence.
+ */
+export declare function importCodexJsonl(outbox: DurableOutbox, filePath: string, context?: CaptureDeliveryContext, captureContent?: boolean): Promise<CodexImportResult>;
+export declare function flushIfConfigured(outbox: DurableOutbox, config: CaptureTransportConfiguration | null): Promise<void>;

package/dist/src/host.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importCodexJsonl = importCodexJsonl;
+exports.flushIfConfigured = flushIfConfigured;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const canonical_1 = require("./canonical");
+const providers_1 = require("./providers");
+const transport_1 = require("./transport");
+function parseCodexCheckpoint(cursor) {
+    if (!cursor)
+        return null;
+    try {
+        const parsed = JSON.parse(cursor);
+        const completedLines = parsed.completedLines;
+        if (parsed.version === 2 && Number.isInteger(completedLines) && completedLines !== undefined && completedLines >= 0 && typeof parsed.sourceGenerationId === 'string' && parsed.sourceGenerationId) {
+            return { version: 2, completedLines, lastLineHash: typeof parsed.lastLineHash === 'string' ? parsed.lastLineHash : undefined, sourceGenerationId: parsed.sourceGenerationId };
+        }
+    }
+    catch { /* legacy cursor */ }
+    const legacy = /^line:(\d+)$/.exec(cursor);
+    return legacy ? { version: 2, completedLines: Number(legacy[1]), sourceGenerationId: '' } : null;
+}
+function checkpointCursor(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+function sourceGenerationId(filePath, firstLine, file) {
+    // This generation only changes on a detected rotation/reset. Appending to
+    // the same JSONL file retains the checkpoint's existing generation.
+    return `codex-jsonl-${(0, canonical_1.sha256)({ filePath, firstLineHash: firstLine ? (0, canonical_1.sha256)(firstLine) : null, inode: file.ino, mtimeMs: file.mtimeMs })}`;
+}
+/**
+ * Imports only unseen Codex JSONL lines. A file truncation/reset is treated as
+ * a new source generation rather than silently skipping fresh evidence.
+ */
+async function importCodexJsonl(outbox, filePath, context, captureContent = false) {
+    const scope = `codex-jsonl:${filePath}`;
+    const [storedCheckpoint, raw, file] = await Promise.all([outbox.getCheckpoint('codex', scope), (0, promises_1.readFile)(filePath, 'utf8'), (0, promises_1.stat)(filePath)]);
+    // JSONL writers can leave their final record half-written. Import only
+    // newline-terminated records and leave the partial tail for the next pass.
+    const split = raw.split(/\r?\n/);
+    const lines = split.slice(0, -1);
+    const checkpoint = parseCodexCheckpoint(storedCheckpoint?.cursor);
+    const completedLines = checkpoint?.completedLines || 0;
+    // A line-count cursor alone cannot distinguish a replacement of equal size.
+    // The durable hash of the last consumed line catches truncation, rotation and
+    // replacement without ever storing the source record itself.
+    const checkpointMatches = Boolean(checkpoint && completedLines <= lines.length && (!checkpoint.lastLineHash || completedLines === 0 || checkpoint.lastLineHash === (0, canonical_1.sha256)(lines[completedLines - 1])));
+    const rotated = Boolean(checkpoint && !checkpointMatches);
+    const start = rotated ? 0 : completedLines;
+    const generationId = checkpoint && !rotated && checkpoint.sourceGenerationId
+        ? checkpoint.sourceGenerationId
+        : sourceGenerationId(filePath, lines[0], file);
+    let imported = 0;
+    let skipped = 0;
+    let deferred = raw.length > 0 && !(raw.endsWith('\n') || raw.endsWith('\r\n')) ? 1 : 0;
+    let consumed = start;
+    for (let index = start; index < lines.length; index += 1) {
+        try {
+            const observation = (0, providers_1.fromCodexJsonl)(JSON.parse(lines[index]), (0, node_path_1.basename)(filePath), captureContent);
+            if (!observation) {
+                skipped += 1;
+                consumed = index + 1;
+                continue;
+            }
+            // Provider-provided generation identifiers win. For plain JSONL logs,
+            // the host-generated source generation makes a rotated file a distinct
+            // server session rather than a conflicting replay of old event IDs.
+            observation.sourceGenerationId ||= generationId;
+            const result = await outbox.enqueue(observation, context);
+            if (result.status === 'ENQUEUED')
+                imported += 1;
+            else
+                skipped += 1;
+            consumed = index + 1;
+        }
+        catch {
+            // Do not advance the checkpoint across a malformed complete line. It
+            // may be a writer flush race despite the newline; advancing would make
+            // fresh evidence disappear permanently. Later lines wait behind it so
+            // sequence ordering remains truthful.
+            deferred += lines.length - index;
+            break;
+        }
+    }
+    await outbox.checkpoint('codex', scope, checkpointCursor({ version: 2, completedLines: consumed, lastLineHash: consumed ? (0, canonical_1.sha256)(lines[consumed - 1]) : undefined, sourceGenerationId: generationId }));
+    return { imported, skipped, deferred, rotated };
+}
+async function flushIfConfigured(outbox, config) {
+    if (config)
+        await new transport_1.CaptureHttpTransport(outbox, config).flush();
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export * from './fileOutbox';
+export * from './types';
+export * from './redaction';
+export * from './providers';
+export * from './transport';
+export * from './host';
+export * from './localHost';
+export * from './service';

package/dist/src/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fileOutbox"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./redaction"), exports);
+__exportStar(require("./providers"), exports);
+__exportStar(require("./transport"), exports);
+__exportStar(require("./host"), exports);
+__exportStar(require("./localHost"), exports);
+__exportStar(require("./service"), exports);

package/dist/src/localHost.d.ts

@@ -0,0 +1,81 @@
+import type { CaptureRepositoryReference } from '@zewstid/zeye-shared';
+declare const ZEYE_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "SubagentStart", "SubagentStop", "PreCompact"];
+export type ClaudeHookEvent = typeof ZEYE_HOOK_EVENTS[number];
+export type RepositoryIdentity = {
+    repositoryRoot: string;
+    fullName?: string;
+    providerRepositoryId?: string;
+    branch?: string;
+    headCommitSha?: string;
+    remoteUrlHash?: string;
+};
+export type LocalHostConfig = {
+    version: 1;
+    claudeInstalls: Array<{
+        repositoryRoot: string;
+        settingsPath: string;
+        command: string;
+    }>;
+    codexSources: Array<{
+        repositoryRoot: string;
+        jsonlPath: string;
+    }>;
+};
+export declare function localHostConfigPath(environment?: NodeJS.ProcessEnv): string;
+export declare function localOutboxDirectory(repositoryRoot: string, environment?: NodeJS.ProcessEnv): string;
+export declare function ensurePrivateDirectory(directory: string): Promise<void>;
+export declare function readLocalHostConfig(path?: string): Promise<LocalHostConfig>;
+export declare function writeLocalHostConfig(config: LocalHostConfig, path?: string): Promise<void>;
+export declare function discoverRepositoryIdentity(repositoryPath: string, options?: {
+    providerRepositoryId?: string;
+    repositoryId?: string;
+}): Promise<RepositoryIdentity | null>;
+export declare function captureRepositoryReference(identity: RepositoryIdentity | null, repositoryId?: string): CaptureRepositoryReference[];
+export type CaptureLock = {
+    release(): Promise<void>;
+};
+export type CaptureLockOptions = {
+    maxWaitMs?: number;
+    initialRetryDelayMs?: number;
+    maxRetryDelayMs?: number;
+};
+export declare function captureLockStatus(directory: string): Promise<{
+    held: boolean;
+    pid?: number;
+    stale?: boolean;
+}>;
+export declare function acquireCaptureLock(directory: string, options?: CaptureLockOptions): Promise<CaptureLock>;
+export declare function withCaptureLock<T>(directory: string, operation: () => Promise<T>, options?: CaptureLockOptions): Promise<T>;
+export declare function installClaudeHooks(input: {
+    repositoryRoot: string;
+    settingsPath?: string;
+    command?: string;
+    configPath?: string;
+}): Promise<{
+    settingsPath: string;
+    installedEvents: ClaudeHookEvent[];
+}>;
+export declare function uninstallClaudeHooks(input: {
+    repositoryRoot: string;
+    settingsPath?: string;
+    command?: string;
+    configPath?: string;
+}): Promise<{
+    settingsPath: string;
+    removedEvents: ClaudeHookEvent[];
+}>;
+export declare function installCodexSource(input: {
+    repositoryRoot: string;
+    jsonlPath: string;
+    configPath?: string;
+}): Promise<void>;
+export declare function uninstallCodexSource(input: {
+    repositoryRoot: string;
+    jsonlPath?: string;
+    configPath?: string;
+}): Promise<number>;
+export declare function configuredSourcesForRepository(config: LocalHostConfig, repositoryRoot: string): {
+    repositoryRoot: string;
+    jsonlPath: string;
+}[];
+export {};