@creativeintelligence/abbie 0.1.0

package/dist/lib/annotations.js

@@ -0,0 +1,564 @@
+/**
+ * Annotation domain model for preview deployments.
+ *
+ * Provides a portable grammar for structured UI feedback loops that agents
+ * can consume reliably. Tool-agnostic: works whether annotations come from
+ * Vercel comments, Agentation, browser automation, or manual CLI input.
+ *
+ * Design principles:
+ * - Provider-agnostic: no vendor-specific assumptions
+ * - Replayable: all state transitions are sequenced
+ * - Actionable: blocking annotations can be routed to work sessions
+ * - Thread-based: annotations support conversation threads
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function afsSeverityToAnnotation(severity) {
+    switch (severity) {
+        case "blocking":
+            return "critical";
+        case "important":
+            return "warning";
+        case "suggestion":
+            return "info";
+        default:
+            return "info";
+    }
+}
+function annotationSeverityToAfs(severity) {
+    switch (severity) {
+        case "critical":
+            return "blocking";
+        case "error":
+        case "warning":
+            return "important";
+        default:
+            return "suggestion";
+    }
+}
+function afsIntentToAnnotation(intent) {
+    switch (intent) {
+        case "fix":
+            return "bug";
+        case "change":
+            return "suggestion";
+        case "question":
+            return "question";
+        case "approve":
+            return "feedback";
+        default:
+            return "feedback";
+    }
+}
+function annotationIntentToAfs(intent) {
+    switch (intent) {
+        case "bug":
+        case "blocker":
+            return "fix";
+        case "question":
+            return "question";
+        case "suggestion":
+            return "change";
+        default:
+            return "approve";
+    }
+}
+function afsThreadToInternal(thread) {
+    return thread.map((message) => ({
+        id: message.id,
+        author: message.role,
+        body: message.content,
+        timestamp: new Date(message.timestamp).toISOString(),
+    }));
+}
+function internalThreadToAfs(thread) {
+    return thread.map((message) => ({
+        id: message.id,
+        role: message.author === "human" || message.author === "user" ? "human" : "agent",
+        content: message.body,
+        timestamp: Date.parse(message.timestamp),
+    }));
+}
+// ============================================================================
+// Store (file-based, per-preview)
+// ============================================================================
+/**
+ * File-based annotation store.
+ *
+ * Stores annotations as JSON files in .abbie/annotations/{previewId}/.
+ * Events are appended to an NDJSON log for replay.
+ */
+export class AnnotationStore {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath || join(process.cwd(), ".abbie", "annotations");
+    }
+    previewDir(previewId) {
+        const dir = join(this.basePath, previewId);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        return dir;
+    }
+    annotationsFile(previewId) {
+        return join(this.previewDir(previewId), "annotations.json");
+    }
+    eventsFile(previewId) {
+        return join(this.previewDir(previewId), "events.ndjson");
+    }
+    readAnnotations(previewId) {
+        const file = this.annotationsFile(previewId);
+        if (!existsSync(file)) {
+            return [];
+        }
+        try {
+            return JSON.parse(readFileSync(file, "utf-8"));
+        }
+        catch {
+            return [];
+        }
+    }
+    writeAnnotations(previewId, annotations) {
+        writeFileSync(this.annotationsFile(previewId), JSON.stringify(annotations, null, 2));
+    }
+    appendEvent(previewId, event) {
+        const file = this.eventsFile(previewId);
+        const line = `${JSON.stringify(event)}\n`;
+        writeFileSync(file, line, { flag: "a" });
+    }
+    readEvents(previewId) {
+        const file = this.eventsFile(previewId);
+        if (!existsSync(file)) {
+            return [];
+        }
+        try {
+            const lines = readFileSync(file, "utf-8").trim().split("\n");
+            return lines.filter((l) => l.length > 0).map((l) => JSON.parse(l));
+        }
+        catch {
+            return [];
+        }
+    }
+    nextAnnotationSeq(previewId) {
+        const annotations = this.readAnnotations(previewId);
+        if (annotations.length === 0) {
+            return 1;
+        }
+        return Math.max(...annotations.map((a) => a.seq)) + 1;
+    }
+    nextEventSeq(previewId) {
+        const events = this.readEvents(previewId);
+        if (events.length === 0) {
+            return 1;
+        }
+        return Math.max(...events.map((e) => e.seq)) + 1;
+    }
+    // ========================================================================
+    // CRUD
+    // ========================================================================
+    create(opts) {
+        const now = new Date().toISOString();
+        const seq = this.nextAnnotationSeq(opts.previewId);
+        const annotation = {
+            id: randomUUID(),
+            previewId: opts.previewId,
+            status: "pending",
+            severity: opts.severity || "info",
+            intent: opts.intent || "feedback",
+            body: opts.body,
+            target: opts.target,
+            selector: opts.selector,
+            screenshot: opts.screenshot,
+            source: opts.source || "cli",
+            thread: [],
+            seq,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const annotations = this.readAnnotations(opts.previewId);
+        annotations.push(annotation);
+        this.writeAnnotations(opts.previewId, annotations);
+        this.appendEvent(opts.previewId, {
+            type: "annotation.created",
+            annotationId: annotation.id,
+            data: { body: opts.body, severity: annotation.severity, intent: annotation.intent },
+            seq: this.nextEventSeq(opts.previewId),
+            timestamp: now,
+        });
+        return annotation;
+    }
+    /**
+     * Import (create/update) an annotation from Agentation AFS shape.
+     * Preserves source annotation IDs for cross-tool interoperability.
+     */
+    createFromAfs(opts) {
+        const now = new Date().toISOString();
+        const createdAt = Number.isFinite(opts.annotation.timestamp)
+            ? new Date(opts.annotation.timestamp).toISOString()
+            : now;
+        const annotations = this.readAnnotations(opts.previewId);
+        const idx = annotations.findIndex((a) => a.id === opts.annotation.id);
+        const existing = idx >= 0 ? annotations[idx] : null;
+        const base = {
+            id: opts.annotation.id,
+            previewId: opts.previewId,
+            status: opts.annotation.status || "pending",
+            severity: afsSeverityToAnnotation(opts.annotation.severity),
+            intent: afsIntentToAnnotation(opts.annotation.intent),
+            body: opts.annotation.comment,
+            target: opts.annotation.url,
+            selector: opts.annotation.elementPath,
+            source: opts.source || "agentation-afs",
+            thread: afsThreadToInternal(opts.annotation.thread || []),
+            linkedSessionId: existing?.linkedSessionId,
+            metadata: {
+                afs: {
+                    x: opts.annotation.x,
+                    y: opts.annotation.y,
+                    element: opts.annotation.element,
+                    boundingBox: opts.annotation.boundingBox,
+                    reactComponents: opts.annotation.reactComponents,
+                    cssClasses: opts.annotation.cssClasses,
+                    computedStyles: opts.annotation.computedStyles,
+                    accessibility: opts.annotation.accessibility,
+                    nearbyText: opts.annotation.nearbyText,
+                    selectedText: opts.annotation.selectedText,
+                    resolvedAt: opts.annotation.resolvedAt,
+                    resolvedBy: opts.annotation.resolvedBy,
+                },
+            },
+            seq: existing?.seq || this.nextAnnotationSeq(opts.previewId),
+            createdAt: existing?.createdAt || createdAt,
+            updatedAt: now,
+        };
+        if (idx >= 0) {
+            annotations[idx] = {
+                ...existing,
+                ...base,
+                seq: existing.seq,
+                createdAt: existing.createdAt,
+            };
+            this.writeAnnotations(opts.previewId, annotations);
+            this.appendEvent(opts.previewId, {
+                type: "annotation.updated",
+                annotationId: base.id,
+                data: { source: "afs", status: base.status, severity: base.severity, intent: base.intent },
+                seq: this.nextEventSeq(opts.previewId),
+                timestamp: now,
+            });
+            return annotations[idx];
+        }
+        annotations.push(base);
+        this.writeAnnotations(opts.previewId, annotations);
+        this.appendEvent(opts.previewId, {
+            type: "annotation.created",
+            annotationId: base.id,
+            data: { source: "afs", status: base.status, severity: base.severity, intent: base.intent },
+            seq: this.nextEventSeq(opts.previewId),
+            timestamp: now,
+        });
+        return base;
+    }
+    list(previewId, filter) {
+        const annotations = this.readAnnotations(previewId);
+        if (!filter?.status) {
+            return annotations;
+        }
+        return annotations.filter((a) => a.status === filter.status);
+    }
+    get(previewId, annotationId) {
+        const annotations = this.readAnnotations(previewId);
+        return annotations.find((a) => a.id === annotationId) || null;
+    }
+    acknowledge(previewId, annotationId) {
+        return this.updateStatus(previewId, annotationId, "acknowledged");
+    }
+    resolve(previewId, annotationId) {
+        return this.updateStatus(previewId, annotationId, "resolved");
+    }
+    dismiss(previewId, annotationId) {
+        return this.updateStatus(previewId, annotationId, "dismissed");
+    }
+    reply(previewId, annotationId, author, body) {
+        const annotations = this.readAnnotations(previewId);
+        const idx = annotations.findIndex((a) => a.id === annotationId);
+        if (idx === -1) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const message = {
+            id: randomUUID(),
+            author,
+            body,
+            timestamp: now,
+        };
+        annotations[idx].thread.push(message);
+        annotations[idx].updatedAt = now;
+        this.writeAnnotations(previewId, annotations);
+        this.appendEvent(previewId, {
+            type: "thread.message",
+            annotationId,
+            data: { author, body },
+            seq: this.nextEventSeq(previewId),
+            timestamp: now,
+        });
+        return annotations[idx];
+    }
+    /**
+     * Link an annotation to an agent session for resolution.
+     */
+    linkSession(previewId, annotationId, sessionId) {
+        const annotations = this.readAnnotations(previewId);
+        const idx = annotations.findIndex((a) => a.id === annotationId);
+        if (idx === -1) {
+            return null;
+        }
+        annotations[idx].linkedSessionId = sessionId;
+        annotations[idx].updatedAt = new Date().toISOString();
+        this.writeAnnotations(previewId, annotations);
+        return annotations[idx];
+    }
+    /**
+     * Get all events for replay.
+     */
+    events(previewId) {
+        return this.readEvents(previewId);
+    }
+    /**
+     * Convert an internal annotation into Agentation AFS shape.
+     */
+    toAfsAnnotation(annotation) {
+        const afs = annotation.metadata?.afs || {};
+        const x = typeof afs.x === "number" ? afs.x : 50;
+        const y = typeof afs.y === "number" ? afs.y : 0;
+        const element = typeof afs.element === "string" ? afs.element : "div";
+        return {
+            id: annotation.id,
+            comment: annotation.body,
+            elementPath: annotation.selector || "body",
+            timestamp: Date.parse(annotation.createdAt),
+            x,
+            y,
+            element,
+            ...(annotation.target ? { url: annotation.target } : {}),
+            ...(afs.boundingBox && typeof afs.boundingBox === "object"
+                ? { boundingBox: afs.boundingBox }
+                : {}),
+            ...(typeof afs.reactComponents === "string" ? { reactComponents: afs.reactComponents } : {}),
+            ...(typeof afs.cssClasses === "string" ? { cssClasses: afs.cssClasses } : {}),
+            ...(typeof afs.computedStyles === "string" ? { computedStyles: afs.computedStyles } : {}),
+            ...(typeof afs.accessibility === "string" ? { accessibility: afs.accessibility } : {}),
+            ...(typeof afs.nearbyText === "string" ? { nearbyText: afs.nearbyText } : {}),
+            ...(typeof afs.selectedText === "string" ? { selectedText: afs.selectedText } : {}),
+            intent: annotationIntentToAfs(annotation.intent),
+            severity: annotationSeverityToAfs(annotation.severity),
+            status: annotation.status,
+            ...(typeof afs.resolvedAt === "string" ? { resolvedAt: afs.resolvedAt } : {}),
+            ...(afs.resolvedBy === "human" || afs.resolvedBy === "agent"
+                ? { resolvedBy: afs.resolvedBy }
+                : {}),
+            ...(annotation.thread.length > 0 ? { thread: internalThreadToAfs(annotation.thread) } : {}),
+        };
+    }
+    exportAfs(previewId, annotationId) {
+        const annotation = this.get(previewId, annotationId);
+        if (!annotation) {
+            return null;
+        }
+        return this.toAfsAnnotation(annotation);
+    }
+    listAfs(previewId, filter) {
+        return this.list(previewId, filter).map((annotation) => this.toAfsAnnotation(annotation));
+    }
+    /**
+     * Batch import AFS annotations into a preview.
+     */
+    importAfsBatch(opts) {
+        return opts.annotations.map((afs) => this.createFromAfs({ previewId: opts.previewId, annotation: afs, source: opts.source }));
+    }
+    /**
+     * Batch export annotations as AFS payloads.
+     */
+    exportAfsBatch(previewId, filter) {
+        return this.listAfs(previewId, filter);
+    }
+    /**
+     * Delete an annotation and emit annotation.deleted event.
+     */
+    delete(previewId, annotationId) {
+        const annotations = this.readAnnotations(previewId);
+        const idx = annotations.findIndex((a) => a.id === annotationId);
+        if (idx === -1) {
+            return null;
+        }
+        const deleted = annotations.splice(idx, 1)[0];
+        this.writeAnnotations(previewId, annotations);
+        this.appendEvent(previewId, {
+            type: "annotation.deleted",
+            annotationId,
+            data: { body: deleted.body, status: deleted.status },
+            seq: this.nextEventSeq(previewId),
+            timestamp: new Date().toISOString(),
+        });
+        return deleted;
+    }
+    /**
+     * Export events as event envelopes with preview/session context.
+     */
+    exportEvents(previewId, opts) {
+        const events = this.readEvents(previewId);
+        const annotations = this.readAnnotations(previewId);
+        return events.map((event) => {
+            const annotation = annotations.find((a) => a.id === event.annotationId);
+            return {
+                version: "1.0",
+                previewId,
+                sessionId: opts?.sessionId ?? annotation?.linkedSessionId,
+                event,
+            };
+        });
+    }
+    // ========================================================================
+    // AFS event ingestion pipeline
+    // ========================================================================
+    /**
+     * Ingest an ordered stream of AFS events into the annotation store.
+     *
+     * Maps external AFS lifecycle events (created, updated, resolved, deleted,
+     * thread.message) into the internal domain model. Preserves ordering via
+     * monotonic seq numbers. Returns the annotations that were touched.
+     */
+    ingestAfsEvents(opts) {
+        const touched = new Map();
+        let ingested = 0;
+        for (const afsEvent of opts.events) {
+            ingested += this.ingestAfsEvent(opts.previewId, afsEvent, touched, opts.source);
+        }
+        return { ingested, annotations: Array.from(touched.values()) };
+    }
+    // ========================================================================
+    // Session routing
+    // ========================================================================
+    /**
+     * Get actionable annotations: unresolved with blocking severity or blocker intent.
+     */
+    getActionable(previewId) {
+        const annotations = this.readAnnotations(previewId);
+        return annotations.filter((a) => a.status !== "resolved" &&
+            a.status !== "dismissed" &&
+            (a.severity === "critical" || a.severity === "error" || a.intent === "blocker"));
+    }
+    /**
+     * Bulk-link all unlinked blocking/critical annotations to a work session.
+     * Returns the annotations that were linked.
+     */
+    routeBlockingToSession(previewId, sessionId) {
+        const actionable = this.getActionable(previewId);
+        const unlinked = actionable.filter((a) => !a.linkedSessionId);
+        const linked = [];
+        for (const annotation of unlinked) {
+            const result = this.linkSession(previewId, annotation.id, sessionId);
+            if (result) {
+                linked.push(result);
+            }
+        }
+        return linked;
+    }
+    // ========================================================================
+    // Private helpers
+    // ========================================================================
+    updateStatus(previewId, annotationId, status) {
+        const annotations = this.readAnnotations(previewId);
+        const idx = annotations.findIndex((a) => a.id === annotationId);
+        if (idx === -1) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const prev = annotations[idx].status;
+        annotations[idx].status = status;
+        annotations[idx].updatedAt = now;
+        this.writeAnnotations(previewId, annotations);
+        this.appendEvent(previewId, {
+            type: "status.changed",
+            annotationId,
+            data: { from: prev, to: status },
+            seq: this.nextEventSeq(previewId),
+            timestamp: now,
+        });
+        return annotations[idx];
+    }
+    ingestAfsEvent(previewId, event, touched, source) {
+        switch (event.type) {
+            case "annotation.created":
+            case "annotation.updated":
+                return this.ingestAfsUpsert(previewId, event, touched, source);
+            case "annotation.resolved":
+                return this.ingestAfsResolved(previewId, event, touched);
+            case "annotation.deleted":
+                return this.ingestAfsDeleted(previewId, event);
+            case "thread.message":
+                return this.ingestAfsThreadMessage(previewId, event, touched);
+            default:
+                return 0;
+        }
+    }
+    ingestAfsUpsert(previewId, event, touched, source) {
+        if (!event.data.annotation) {
+            return 0;
+        }
+        const upserted = this.createFromAfs({
+            previewId,
+            annotation: event.data.annotation,
+            source,
+        });
+        touched.set(upserted.id, upserted);
+        return 1;
+    }
+    ingestAfsResolved(previewId, event, touched) {
+        const resolved = this.resolve(previewId, event.annotationId);
+        if (!resolved) {
+            return 0;
+        }
+        this.applyResolvedMetadata(previewId, event);
+        const refreshed = this.get(previewId, resolved.id);
+        if (refreshed) {
+            touched.set(refreshed.id, refreshed);
+        }
+        return 1;
+    }
+    applyResolvedMetadata(previewId, event) {
+        if (!event.data.resolvedBy) {
+            return;
+        }
+        const annotations = this.readAnnotations(previewId);
+        const idx = annotations.findIndex((annotation) => annotation.id === event.annotationId);
+        if (idx < 0) {
+            return;
+        }
+        annotations[idx].metadata = {
+            ...annotations[idx].metadata,
+            afs: {
+                ...(annotations[idx].metadata?.afs || {}),
+                resolvedBy: event.data.resolvedBy,
+                resolvedAt: new Date(event.timestamp).toISOString(),
+            },
+        };
+        this.writeAnnotations(previewId, annotations);
+    }
+    ingestAfsDeleted(previewId, event) {
+        return this.delete(previewId, event.annotationId) ? 1 : 0;
+    }
+    ingestAfsThreadMessage(previewId, event, touched) {
+        if (!event.data.message) {
+            return 0;
+        }
+        const message = event.data.message;
+        const replied = this.reply(previewId, event.annotationId, message.role, message.content);
+        if (!replied) {
+            return 0;
+        }
+        touched.set(replied.id, replied);
+        return 1;
+    }
+}

package/dist/lib/auto/discover.d.ts

@@ -0,0 +1,45 @@
+import type { ResourceManager } from "../resources.js";
+export type WorkSource = "linear" | "claude" | "git";
+export interface WorkItem {
+    id: string;
+    source: WorkSource;
+    title: string;
+    details?: string;
+    issue?: string;
+    url?: string;
+    project?: string;
+    priority?: number;
+    effort?: "quick" | "thorough";
+    metadata?: Record<string, unknown>;
+}
+export interface DiscoveryReport {
+    source: WorkSource;
+    status: "ok" | "skipped" | "error";
+    detail?: string;
+    items: number;
+}
+export interface DiscoveryResult {
+    items: WorkItem[];
+    sources: DiscoveryReport[];
+}
+export interface LinearDiscoveryOptions {
+    enabled: boolean;
+    apiKey?: string;
+    apiUrl?: string;
+    limit: number;
+    cachePath?: string;
+    project?: string;
+    team?: string;
+}
+export interface DiscoveryOptions {
+    cwd: string;
+    project?: string;
+    dryRun: boolean;
+    limit: number;
+    staleDays: number;
+    linear: LinearDiscoveryOptions;
+    resources?: ResourceManager;
+    sessionId?: string;
+}
+export declare function discoverWork(options: DiscoveryOptions): Promise<DiscoveryResult>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/lib/auto/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/lib/auto/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD,wBAAsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAmBtF"}