@creativeintelligence/abbie 0.1.0

package/dist/lib/auto/workspace.js

@@ -0,0 +1,229 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Workspace resolution for Luke's Linear setup.
+ *
+ * Source of truth for team keys: ~/.abbie/projects.json
+ */
+let cachedTeamKeys;
+function getTeamKeysFromProjectsJson() {
+    if (cachedTeamKeys)
+        return cachedTeamKeys;
+    const keys = new Set();
+    const projectsPath = join(homedir(), ".abbie", "projects.json");
+    try {
+        if (!existsSync(projectsPath)) {
+            cachedTeamKeys = keys;
+            return keys;
+        }
+        const raw = readFileSync(projectsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        for (const project of Object.values(parsed.projects ?? {})) {
+            if (typeof project.linearTeam === "string" && project.linearTeam.trim()) {
+                keys.add(project.linearTeam.toUpperCase());
+            }
+        }
+    }
+    catch {
+        // ignore - treat as no known team keys
+    }
+    cachedTeamKeys = keys;
+    return keys;
+}
+/**
+ * Environment variable names for each workspace's API key.
+ */
+const WORKSPACE_API_KEY_ENV = {
+    "luke-labs": "LINEAR_API_KEY_LUKE_LABS",
+};
+/**
+ * Read .loop.json from the given directory.
+ */
+export function readLoopConfig(cwd) {
+    const configPath = join(cwd, ".loop.json");
+    if (!existsSync(configPath)) {
+        return undefined;
+    }
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get the workspace for a given team.
+ */
+export function getWorkspaceForTeam(team) {
+    const teamKey = team.toUpperCase();
+    const knownTeams = getTeamKeysFromProjectsJson();
+    if (knownTeams.has(teamKey)) {
+        return "luke-labs";
+    }
+    return undefined;
+}
+/**
+ * Get the API key for a given workspace.
+ * Checks workspace-specific env vars first, then falls back to LINEAR_API_KEY.
+ */
+export function getApiKeyForWorkspace(workspace) {
+    // First try workspace-specific env var
+    const envName = WORKSPACE_API_KEY_ENV[workspace];
+    if (envName && process.env[envName]) {
+        return process.env[envName];
+    }
+    // Fall back to default LINEAR_API_KEY
+    return process.env.LINEAR_API_KEY;
+}
+/**
+ * Parse LINEAR_API_KEYS env var (comma-separated list of keys).
+ */
+export function parseLinearApiKeys() {
+    const keys = process.env.LINEAR_API_KEYS;
+    if (!keys)
+        return [];
+    return keys
+        .split(",")
+        .map((k) => k.trim())
+        .filter(Boolean);
+}
+/**
+ * Find an API key from LINEAR_API_KEYS that has access to the expected team.
+ * This is async because it needs to query the Linear API.
+ */
+export async function findApiKeyForTeam(expectedTeam) {
+    const keys = parseLinearApiKeys();
+    if (keys.length === 0)
+        return undefined;
+    for (const key of keys) {
+        const result = await validateApiKeyForTeam(key, expectedTeam);
+        if (result.valid) {
+            return key;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the correct Linear API key for the current directory.
+ *
+ * Resolution order:
+ * 1. Read team from .loop.json
+ * 2. Map team to workspace
+ * 3. Get API key for workspace from environment
+ * 4. Fall back to LINEAR_API_KEY if no workspace-specific key
+ */
+export function resolveLinearApiKey(cwd) {
+    // Try to read .loop.json
+    const loopConfig = readLoopConfig(cwd);
+    const team = loopConfig?.project?.team;
+    if (!team) {
+        // No team configured, use default
+        return {
+            team: undefined,
+            workspace: undefined,
+            apiKey: process.env.LINEAR_API_KEY,
+            source: "fallback",
+            warning: "No team in .loop.json, using default LINEAR_API_KEY",
+        };
+    }
+    const workspace = getWorkspaceForTeam(team);
+    if (!workspace) {
+        // Unknown team, use default
+        return {
+            team,
+            workspace: undefined,
+            apiKey: process.env.LINEAR_API_KEY,
+            source: "fallback",
+            warning: `Unknown team "${team}", using default LINEAR_API_KEY`,
+        };
+    }
+    // Try workspace-specific API key
+    const envName = WORKSPACE_API_KEY_ENV[workspace];
+    const workspaceApiKey = envName ? process.env[envName] : undefined;
+    if (workspaceApiKey) {
+        return {
+            team,
+            workspace,
+            apiKey: workspaceApiKey,
+            source: "env",
+        };
+    }
+    // Fall back to default
+    return {
+        team,
+        workspace,
+        apiKey: process.env.LINEAR_API_KEY,
+        source: "fallback",
+        warning: `No ${envName} set for workspace "${workspace}", using default LINEAR_API_KEY which may be wrong workspace`,
+    };
+}
+/**
+ * Async version of resolveLinearApiKey that validates the key has access
+ * to the expected team and falls back to LINEAR_API_KEYS if needed.
+ */
+export async function resolveLinearApiKeyAsync(cwd) {
+    // First get the sync resolution
+    const syncResult = resolveLinearApiKey(cwd);
+    // If no team or no API key, nothing to validate
+    if (!syncResult.team || !syncResult.apiKey) {
+        return syncResult;
+    }
+    // Validate the resolved key has access to the expected team
+    const validation = await validateApiKeyForTeam(syncResult.apiKey, syncResult.team);
+    if (validation.valid) {
+        return syncResult;
+    }
+    // Key doesn't have access - try LINEAR_API_KEYS fallback
+    const fallbackKey = await findApiKeyForTeam(syncResult.team);
+    if (fallbackKey) {
+        return {
+            team: syncResult.team,
+            workspace: syncResult.workspace,
+            apiKey: fallbackKey,
+            source: "env",
+            warning: `Used LINEAR_API_KEYS fallback (${syncResult.source} key lacked access to ${syncResult.team})`,
+        };
+    }
+    // No valid key found - return original with warning
+    return {
+        ...syncResult,
+        warning: `No API key found with access to team "${syncResult.team}". Available: ${validation.actualTeams?.join(", ") || "none"}`,
+    };
+}
+/**
+ * Validate that the API key has access to the expected team.
+ * Returns true if validation passes or can't be performed.
+ */
+export async function validateApiKeyForTeam(apiKey, expectedTeam) {
+    try {
+        const response = await fetch("https://api.linear.app/graphql", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: apiKey,
+            },
+            body: JSON.stringify({
+                query: `query { teams { nodes { key name } } }`,
+            }),
+        });
+        if (!response.ok) {
+            return { valid: false, error: `API error: ${response.status}` };
+        }
+        const data = (await response.json());
+        const teams = data?.data?.teams?.nodes || [];
+        const teamKeys = teams.map((t) => t.key);
+        const hasTeam = teamKeys.some((k) => k.toUpperCase() === expectedTeam.toUpperCase());
+        return {
+            valid: hasTeam,
+            actualTeams: teamKeys,
+            error: hasTeam
+                ? undefined
+                : `Team "${expectedTeam}" not found. Available: ${teamKeys.join(", ")}`,
+        };
+    }
+    catch (err) {
+        return { valid: false, error: err.message };
+    }
+}

package/dist/lib/backlog.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Backlog item status.
+ */
+export type BacklogStatus = "pending" | "claimed" | "in_progress" | "blocked" | "completed" | "abandoned";
+/**
+ * Backlog item representing a work item.
+ */
+export interface BacklogItem {
+    id: string;
+    type: "issue" | "pr" | "task";
+    ref: string;
+    title: string;
+    project: string;
+    priority: number;
+    status: BacklogStatus;
+    claimed_by?: string;
+    claimed_at?: string;
+    source: "linear" | "github" | "manual";
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Claim result.
+ */
+export interface ClaimResult {
+    success: boolean;
+    item?: BacklogItem;
+    reason?: string;
+}
+/**
+ * Backlog manager for work item deduplication.
+ */
+export declare class BacklogManager {
+    private basePath;
+    constructor(basePath?: string);
+    /**
+     * Get item file path.
+     */
+    private getItemPath;
+    /**
+     * Generate a unique item ID.
+     */
+    private generateId;
+    /**
+     * Add an item to the backlog.
+     */
+    add(item: Omit<BacklogItem, "id" | "status" | "created_at" | "updated_at">): BacklogItem;
+    /**
+     * Find item by reference (e.g., ZO-123).
+     */
+    findByRef(project: string, ref: string): BacklogItem | undefined;
+    /**
+     * Get an item by ID.
+     */
+    get(project: string, id: string): BacklogItem | undefined;
+    /**
+     * Update an item.
+     */
+    update(project: string, id: string, updates: Partial<BacklogItem>): BacklogItem | undefined;
+    /**
+     * Claim an item for a session.
+     */
+    claim(project: string, id: string, sessionId: string): ClaimResult;
+    /**
+     * Start work on a claimed item.
+     */
+    startWork(project: string, id: string, sessionId: string): ClaimResult;
+    /**
+     * Mark item as blocked.
+     */
+    block(project: string, id: string, reason: string): BacklogItem | undefined;
+    /**
+     * Complete an item.
+     */
+    complete(project: string, id: string): BacklogItem | undefined;
+    /**
+     * Abandon an item (release claim).
+     */
+    abandon(project: string, id: string): BacklogItem | undefined;
+    /**
+     * Release a claim without abandoning.
+     */
+    release(project: string, id: string): BacklogItem | undefined;
+    /**
+     * List all items for a project.
+     */
+    listItems(project: string): BacklogItem[];
+    /**
+     * Get pending items (unclaimed, not blocked).
+     */
+    getPending(project: string): BacklogItem[];
+    /**
+     * Get items claimed by a session.
+     */
+    getBySession(project: string, sessionId: string): BacklogItem[];
+    /**
+     * Get the next available item (highest priority, unclaimed).
+     */
+    getNext(project: string): BacklogItem | undefined;
+    /**
+     * Pick and claim the next available item.
+     */
+    pickNext(project: string, sessionId: string): ClaimResult;
+    /**
+     * Sync from Linear issues.
+     */
+    syncFromLinear(project: string, issues: Array<{
+        id: string;
+        title: string;
+        priority: number;
+        identifier: string;
+    }>): number;
+    /**
+     * Sync from GitHub PRs/issues.
+     */
+    syncFromGitHub(project: string, items: Array<{
+        number: number;
+        title: string;
+        type: "issue" | "pr";
+    }>): number;
+    /**
+     * Clean up completed/abandoned items older than N days.
+     */
+    cleanup(project: string, olderThanDays?: number): number;
+    /**
+     * List all projects with backlog items.
+     */
+    listProjects(): string[];
+}
+export declare function getBacklogManager(): BacklogManager;
+/**
+ * Add a new item to the backlog.
+ */
+export declare function addBacklogItem(item: Omit<BacklogItem, "id" | "status" | "created_at" | "updated_at">): BacklogItem;
+/**
+ * Claim a backlog item for a session.
+ */
+export declare function claimBacklogItem(project: string, id: string, sessionId: string): ClaimResult;
+//# sourceMappingURL=backlog.d.ts.map

package/dist/lib/backlog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.d.ts","sourceRoot":"","sources":["../../src/lib/backlog.ts"],"names":[],"mappings":"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"}

package/dist/lib/backlog.js

@@ -0,0 +1,317 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/**
+ * Backlog manager for work item deduplication.
+ */
+export class BacklogManager {
+    basePath;
+    constructor(basePath = "~/.abbie/backlog") {
+        this.basePath = basePath.replace("~", process.env.HOME || "");
+        if (!existsSync(this.basePath)) {
+            mkdirSync(this.basePath, { recursive: true });
+        }
+    }
+    /**
+     * Get item file path.
+     */
+    getItemPath(project, id) {
+        const projectDir = join(this.basePath, project);
+        if (!existsSync(projectDir)) {
+            mkdirSync(projectDir, { recursive: true });
+        }
+        return join(projectDir, `${id}.json`);
+    }
+    /**
+     * Generate a unique item ID.
+     */
+    generateId() {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).slice(2, 6);
+        return `${timestamp}-${random}`;
+    }
+    /**
+     * Add an item to the backlog.
+     */
+    add(item) {
+        const id = this.generateId();
+        const now = new Date().toISOString();
+        const fullItem = {
+            ...item,
+            id,
+            status: "pending",
+            created_at: now,
+            updated_at: now,
+        };
+        // Check for duplicates
+        const existing = this.findByRef(item.project, item.ref);
+        if (existing) {
+            return existing;
+        }
+        const path = this.getItemPath(item.project, id);
+        writeFileSync(path, JSON.stringify(fullItem, null, 2));
+        return fullItem;
+    }
+    /**
+     * Find item by reference (e.g., ZO-123).
+     */
+    findByRef(project, ref) {
+        const items = this.listItems(project);
+        return items.find((item) => item.ref === ref);
+    }
+    /**
+     * Get an item by ID.
+     */
+    get(project, id) {
+        const path = this.getItemPath(project, id);
+        if (!existsSync(path)) {
+            return undefined;
+        }
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    /**
+     * Update an item.
+     */
+    update(project, id, updates) {
+        const item = this.get(project, id);
+        if (!item) {
+            return undefined;
+        }
+        const updated = {
+            ...item,
+            ...updates,
+            id: item.id, // Prevent ID change
+            updated_at: new Date().toISOString(),
+        };
+        const path = this.getItemPath(project, id);
+        writeFileSync(path, JSON.stringify(updated, null, 2));
+        return updated;
+    }
+    /**
+     * Claim an item for a session.
+     */
+    claim(project, id, sessionId) {
+        const item = this.get(project, id);
+        if (!item) {
+            return { success: false, reason: "Item not found" };
+        }
+        // Check if already claimed
+        if (item.claimed_by && item.claimed_by !== sessionId) {
+            return {
+                success: false,
+                reason: `Already claimed by ${item.claimed_by}`,
+                item,
+            };
+        }
+        // Check if in terminal state
+        if (item.status === "completed" || item.status === "abandoned") {
+            return {
+                success: false,
+                reason: `Item is ${item.status}`,
+                item,
+            };
+        }
+        const updated = this.update(project, id, {
+            status: "claimed",
+            claimed_by: sessionId,
+            claimed_at: new Date().toISOString(),
+        });
+        return { success: true, item: updated };
+    }
+    /**
+     * Start work on a claimed item.
+     */
+    startWork(project, id, sessionId) {
+        const item = this.get(project, id);
+        if (!item) {
+            return { success: false, reason: "Item not found" };
+        }
+        if (item.claimed_by !== sessionId) {
+            return { success: false, reason: "Not claimed by this session", item };
+        }
+        const updated = this.update(project, id, { status: "in_progress" });
+        return { success: true, item: updated };
+    }
+    /**
+     * Mark item as blocked.
+     */
+    block(project, id, reason) {
+        return this.update(project, id, {
+            status: "blocked",
+            metadata: { block_reason: reason },
+        });
+    }
+    /**
+     * Complete an item.
+     */
+    complete(project, id) {
+        return this.update(project, id, { status: "completed" });
+    }
+    /**
+     * Abandon an item (release claim).
+     */
+    abandon(project, id) {
+        return this.update(project, id, {
+            status: "abandoned",
+            claimed_by: undefined,
+            claimed_at: undefined,
+        });
+    }
+    /**
+     * Release a claim without abandoning.
+     */
+    release(project, id) {
+        return this.update(project, id, {
+            status: "pending",
+            claimed_by: undefined,
+            claimed_at: undefined,
+        });
+    }
+    /**
+     * List all items for a project.
+     */
+    listItems(project) {
+        const projectDir = join(this.basePath, project);
+        if (!existsSync(projectDir)) {
+            return [];
+        }
+        return readdirSync(projectDir)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => {
+            const content = readFileSync(join(projectDir, f), "utf-8");
+            return JSON.parse(content);
+        })
+            .sort((a, b) => a.priority - b.priority || a.created_at.localeCompare(b.created_at));
+    }
+    /**
+     * Get pending items (unclaimed, not blocked).
+     */
+    getPending(project) {
+        return this.listItems(project).filter((item) => item.status === "pending");
+    }
+    /**
+     * Get items claimed by a session.
+     */
+    getBySession(project, sessionId) {
+        return this.listItems(project).filter((item) => item.claimed_by === sessionId);
+    }
+    /**
+     * Get the next available item (highest priority, unclaimed).
+     */
+    getNext(project) {
+        return this.getPending(project)[0];
+    }
+    /**
+     * Pick and claim the next available item.
+     */
+    pickNext(project, sessionId) {
+        const next = this.getNext(project);
+        if (!next) {
+            return { success: false, reason: "No pending items" };
+        }
+        return this.claim(project, next.id, sessionId);
+    }
+    /**
+     * Sync from Linear issues.
+     */
+    syncFromLinear(project, issues) {
+        let added = 0;
+        for (const issue of issues) {
+            const existing = this.findByRef(project, issue.identifier);
+            if (!existing) {
+                this.add({
+                    type: "issue",
+                    ref: issue.identifier,
+                    title: issue.title,
+                    project,
+                    priority: issue.priority || 3,
+                    source: "linear",
+                    metadata: { linear_id: issue.id },
+                });
+                added++;
+            }
+        }
+        return added;
+    }
+    /**
+     * Sync from GitHub PRs/issues.
+     */
+    syncFromGitHub(project, items) {
+        let added = 0;
+        for (const item of items) {
+            const ref = `#${item.number}`;
+            const existing = this.findByRef(project, ref);
+            if (!existing) {
+                this.add({
+                    type: item.type,
+                    ref,
+                    title: item.title,
+                    project,
+                    priority: 3,
+                    source: "github",
+                    metadata: { github_number: item.number },
+                });
+                added++;
+            }
+        }
+        return added;
+    }
+    /**
+     * Clean up completed/abandoned items older than N days.
+     */
+    cleanup(project, olderThanDays = 30) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - olderThanDays);
+        const cutoffStr = cutoff.toISOString();
+        const items = this.listItems(project);
+        let removed = 0;
+        for (const item of items) {
+            if ((item.status === "completed" || item.status === "abandoned") &&
+                item.updated_at < cutoffStr) {
+                const path = this.getItemPath(project, item.id);
+                unlinkSync(path);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * List all projects with backlog items.
+     */
+    listProjects() {
+        if (!existsSync(this.basePath)) {
+            return [];
+        }
+        return readdirSync(this.basePath).filter((name) => {
+            const path = join(this.basePath, name);
+            try {
+                const stat = require("node:fs").statSync(path);
+                return stat.isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+}
+/**
+ * Create a singleton backlog manager.
+ */
+let _manager;
+export function getBacklogManager() {
+    if (!_manager) {
+        _manager = new BacklogManager();
+    }
+    return _manager;
+}
+/**
+ * Add a new item to the backlog.
+ */
+export function addBacklogItem(item) {
+    return getBacklogManager().add(item);
+}
+/**
+ * Claim a backlog item for a session.
+ */
+export function claimBacklogItem(project, id, sessionId) {
+    return getBacklogManager().claim(project, id, sessionId);
+}

package/dist/lib/backlog.test.d.ts

@@ -0,0 +1 @@
+export {};