@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/multi-agent/artifacts.d.ts

@@ -0,0 +1,197 @@
+/**
+ * ArtifactStore - Storage for team artifacts
+ *
+ * Artifacts are named pieces of work that agents can publish and reference:
+ * - design: Architecture, API specs, data models
+ * - plan: Sprint plans, task breakdowns, timelines
+ * - review: Code reviews, security audits, feedback
+ * - decision: Architectural decisions, trade-off analysis
+ * - note: General notes, meeting summaries
+ */
+/**
+ * Artifact types
+ */
+export type ArtifactType = 'design' | 'plan' | 'review' | 'decision' | 'note';
+/**
+ * Full artifact structure
+ */
+export interface Artifact {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary: string;
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+    mentions: string[];
+    referencedBy: string[];
+}
+/**
+ * Artifact summary for the shared context index
+ */
+export interface ArtifactSummary {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    summary: string;
+    updatedAt: Date;
+}
+/**
+ * Options for creating an artifact
+ */
+export interface CreateArtifactOptions {
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary?: string;
+}
+/**
+ * Options for updating an artifact
+ */
+export interface UpdateArtifactOptions {
+    content?: string;
+    summary?: string;
+    type?: ArtifactType;
+}
+/**
+ * Serialized artifact for persistence
+ */
+export interface SerializedArtifact {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    mentions?: string[];
+    referencedBy?: string[];
+}
+/**
+ * Artifact index for persistence
+ */
+export interface ArtifactIndex {
+    version: number;
+    artifacts: Array<{
+        id: string;
+        name: string;
+        agent: string;
+        type: ArtifactType;
+        summary: string;
+        updatedAt: string;
+    }>;
+    updatedAt: string;
+}
+/**
+ * Manages artifact storage and retrieval
+ */
+export declare class ArtifactStore {
+    private readonly basePath;
+    private readonly artifacts;
+    private readonly nameToId;
+    private updatedAt;
+    constructor(basePath: string);
+    /**
+     * Get the artifacts directory path
+     */
+    private getArtifactsDir;
+    /**
+     * Get the index file path
+     */
+    private getIndexPath;
+    /**
+     * Get the path for an artifact file
+     */
+    private getArtifactPath;
+    /**
+     * Ensure artifacts directory exists
+     */
+    private ensureDir;
+    /**
+     * Create a new artifact
+     */
+    create(options: CreateArtifactOptions): Artifact;
+    /**
+     * Get an artifact by ID
+     */
+    get(id: string): Artifact | undefined;
+    /**
+     * Get an artifact by name (case-insensitive)
+     */
+    getByName(name: string): Artifact | undefined;
+    /**
+     * Update an artifact
+     */
+    update(id: string, options: UpdateArtifactOptions): Artifact | undefined;
+    /**
+     * Delete an artifact
+     */
+    delete(id: string): boolean;
+    /**
+     * Rename an artifact
+     */
+    rename(id: string, newName: string): Artifact | undefined;
+    /**
+     * List all artifacts
+     */
+    list(): Artifact[];
+    /**
+     * List artifacts by agent
+     */
+    listByAgent(agent: string): Artifact[];
+    /**
+     * List artifacts by type
+     */
+    listByType(type: ArtifactType): Artifact[];
+    /**
+     * Search artifacts by name or content
+     */
+    search(query: string): Artifact[];
+    /**
+     * Get artifact count
+     */
+    get size(): number;
+    /**
+     * Check if an artifact exists by name
+     */
+    has(name: string): boolean;
+    /**
+     * Check if an artifact exists by ID
+     */
+    hasId(id: string): boolean;
+    /**
+     * Generate a summary from content
+     * Simple extraction of first meaningful lines
+     */
+    private generateSummary;
+    /**
+     * Get summaries for shared context injection
+     */
+    getSummaries(): ArtifactSummary[];
+    /**
+     * Save all artifacts to disk
+     */
+    save(): void;
+    /**
+     * Save just the index file
+     */
+    private saveIndex;
+    /**
+     * Load artifacts from disk
+     */
+    load(): void;
+    /**
+     * Clear all artifacts (including from disk)
+     */
+    clear(): void;
+    /**
+     * Get the last update timestamp
+     */
+    getLastUpdated(): Date;
+}

package/dist/multi-agent/artifacts.js

@@ -0,0 +1,379 @@
+/**
+ * ArtifactStore - Storage for team artifacts
+ *
+ * Artifacts are named pieces of work that agents can publish and reference:
+ * - design: Architecture, API specs, data models
+ * - plan: Sprint plans, task breakdowns, timelines
+ * - review: Code reviews, security audits, feedback
+ * - decision: Architectural decisions, trade-off analysis
+ * - note: General notes, meeting summaries
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { truncatePlain as truncate } from '@compilr-dev/ui-core/utils';
+// =============================================================================
+// Constants
+// =============================================================================
+const MAX_SUMMARY_LENGTH = 200;
+const ARTIFACTS_DIR = 'artifacts';
+const INDEX_FILE = 'index.json';
+// =============================================================================
+// ArtifactStore
+// =============================================================================
+/**
+ * Manages artifact storage and retrieval
+ */
+export class ArtifactStore {
+    basePath;
+    artifacts = new Map();
+    nameToId = new Map(); // name -> id lookup
+    updatedAt = new Date();
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+    // ---------------------------------------------------------------------------
+    // Path Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Get the artifacts directory path
+     */
+    getArtifactsDir() {
+        return path.join(this.basePath, ARTIFACTS_DIR);
+    }
+    /**
+     * Get the index file path
+     */
+    getIndexPath() {
+        return path.join(this.getArtifactsDir(), INDEX_FILE);
+    }
+    /**
+     * Get the path for an artifact file
+     */
+    getArtifactPath(id) {
+        return path.join(this.getArtifactsDir(), `${id}.json`);
+    }
+    /**
+     * Ensure artifacts directory exists
+     */
+    ensureDir() {
+        const dir = this.getArtifactsDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // CRUD Operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new artifact
+     */
+    create(options) {
+        const id = `art-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`;
+        // Generate summary if not provided
+        const summary = options.summary ?? this.generateSummary(options.content);
+        const artifact = {
+            id,
+            name: options.name,
+            agent: options.agent,
+            type: options.type,
+            content: options.content,
+            summary,
+            version: 1,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            mentions: [],
+            referencedBy: [],
+        };
+        this.artifacts.set(id, artifact);
+        this.nameToId.set(options.name.toLowerCase(), id);
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    /**
+     * Get an artifact by ID
+     */
+    get(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Get an artifact by name (case-insensitive)
+     */
+    getByName(name) {
+        const id = this.nameToId.get(name.toLowerCase());
+        if (id) {
+            return this.artifacts.get(id);
+        }
+        return undefined;
+    }
+    /**
+     * Update an artifact
+     */
+    update(id, options) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return undefined;
+        }
+        if (options.content !== undefined) {
+            artifact.content = options.content;
+            // Regenerate summary if content changed and no new summary provided
+            if (options.summary === undefined) {
+                artifact.summary = this.generateSummary(options.content);
+            }
+        }
+        if (options.summary !== undefined) {
+            artifact.summary = options.summary;
+        }
+        if (options.type !== undefined) {
+            artifact.type = options.type;
+        }
+        artifact.version++;
+        artifact.updatedAt = new Date();
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    /**
+     * Delete an artifact
+     */
+    delete(id) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return false;
+        }
+        this.nameToId.delete(artifact.name.toLowerCase());
+        this.artifacts.delete(id);
+        this.updatedAt = new Date();
+        // Remove file if persisted
+        const filePath = this.getArtifactPath(id);
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+        return true;
+    }
+    /**
+     * Rename an artifact
+     */
+    rename(id, newName) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return undefined;
+        }
+        // Update name lookup
+        this.nameToId.delete(artifact.name.toLowerCase());
+        artifact.name = newName;
+        this.nameToId.set(newName.toLowerCase(), id);
+        artifact.updatedAt = new Date();
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    // ---------------------------------------------------------------------------
+    // Query Operations
+    // ---------------------------------------------------------------------------
+    /**
+     * List all artifacts
+     */
+    list() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * List artifacts by agent
+     */
+    listByAgent(agent) {
+        return this.list().filter(a => a.agent === agent);
+    }
+    /**
+     * List artifacts by type
+     */
+    listByType(type) {
+        return this.list().filter(a => a.type === type);
+    }
+    /**
+     * Search artifacts by name or content
+     */
+    search(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.list().filter(a => a.name.toLowerCase().includes(lowerQuery) ||
+            a.content.toLowerCase().includes(lowerQuery) ||
+            a.summary.toLowerCase().includes(lowerQuery));
+    }
+    /**
+     * Get artifact count
+     */
+    get size() {
+        return this.artifacts.size;
+    }
+    /**
+     * Check if an artifact exists by name
+     */
+    has(name) {
+        return this.nameToId.has(name.toLowerCase());
+    }
+    /**
+     * Check if an artifact exists by ID
+     */
+    hasId(id) {
+        return this.artifacts.has(id);
+    }
+    // ---------------------------------------------------------------------------
+    // Summary Generation
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate a summary from content
+     * Simple extraction of first meaningful lines
+     */
+    generateSummary(content) {
+        // Remove markdown headers and get first meaningful content
+        const lines = content
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line.length > 0 && !line.startsWith('#'));
+        const summary = lines.slice(0, 3).join(' ');
+        if (summary.length > MAX_SUMMARY_LENGTH) {
+            return truncate(summary, MAX_SUMMARY_LENGTH);
+        }
+        return summary || 'No summary available';
+    }
+    // ---------------------------------------------------------------------------
+    // Index for Shared Context
+    // ---------------------------------------------------------------------------
+    /**
+     * Get summaries for shared context injection
+     */
+    getSummaries() {
+        return this.list()
+            .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())
+            .map(a => ({
+            id: a.id,
+            name: a.name,
+            agent: a.agent,
+            type: a.type,
+            summary: a.summary,
+            updatedAt: a.updatedAt,
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // Persistence
+    // ---------------------------------------------------------------------------
+    /**
+     * Save all artifacts to disk
+     */
+    save() {
+        this.ensureDir();
+        // Save each artifact
+        for (const artifact of this.artifacts.values()) {
+            const filePath = this.getArtifactPath(artifact.id);
+            const serialized = {
+                id: artifact.id,
+                name: artifact.name,
+                agent: artifact.agent,
+                type: artifact.type,
+                content: artifact.content,
+                summary: artifact.summary,
+                version: artifact.version,
+                createdAt: artifact.createdAt.toISOString(),
+                updatedAt: artifact.updatedAt.toISOString(),
+                mentions: artifact.mentions,
+                referencedBy: artifact.referencedBy,
+            };
+            fs.writeFileSync(filePath, JSON.stringify(serialized, null, 2), 'utf-8');
+        }
+        // Save index
+        this.saveIndex();
+    }
+    /**
+     * Save just the index file
+     */
+    saveIndex() {
+        this.ensureDir();
+        const index = {
+            version: 1,
+            artifacts: this.getSummaries().map(a => ({
+                id: a.id,
+                name: a.name,
+                agent: a.agent,
+                type: a.type,
+                summary: a.summary,
+                updatedAt: a.updatedAt.toISOString(),
+            })),
+            updatedAt: this.updatedAt.toISOString(),
+        };
+        fs.writeFileSync(this.getIndexPath(), JSON.stringify(index, null, 2), 'utf-8');
+    }
+    /**
+     * Load artifacts from disk
+     */
+    load() {
+        const dir = this.getArtifactsDir();
+        if (!fs.existsSync(dir)) {
+            return;
+        }
+        // Load index first to get list of artifacts
+        const indexPath = this.getIndexPath();
+        if (!fs.existsSync(indexPath)) {
+            return;
+        }
+        try {
+            const indexContent = fs.readFileSync(indexPath, 'utf-8');
+            const index = JSON.parse(indexContent);
+            // Load each artifact file
+            for (const entry of index.artifacts) {
+                const filePath = this.getArtifactPath(entry.id);
+                if (fs.existsSync(filePath)) {
+                    try {
+                        const content = fs.readFileSync(filePath, 'utf-8');
+                        const serialized = JSON.parse(content);
+                        const artifact = {
+                            id: serialized.id,
+                            name: serialized.name,
+                            agent: serialized.agent,
+                            type: serialized.type,
+                            content: serialized.content,
+                            summary: serialized.summary,
+                            version: serialized.version,
+                            createdAt: new Date(serialized.createdAt),
+                            updatedAt: new Date(serialized.updatedAt),
+                            mentions: serialized.mentions ?? [],
+                            referencedBy: serialized.referencedBy ?? [],
+                        };
+                        this.artifacts.set(artifact.id, artifact);
+                        this.nameToId.set(artifact.name.toLowerCase(), artifact.id);
+                    }
+                    catch {
+                        // Skip invalid artifact files
+                    }
+                }
+            }
+            this.updatedAt = new Date(index.updatedAt);
+        }
+        catch {
+            // Index corrupted, start fresh
+            this.artifacts.clear();
+            this.nameToId.clear();
+        }
+    }
+    /**
+     * Clear all artifacts (including from disk)
+     */
+    clear() {
+        // Delete all artifact files
+        for (const id of this.artifacts.keys()) {
+            const filePath = this.getArtifactPath(id);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        // Delete index
+        const indexPath = this.getIndexPath();
+        if (fs.existsSync(indexPath)) {
+            fs.unlinkSync(indexPath);
+        }
+        this.artifacts.clear();
+        this.nameToId.clear();
+        this.updatedAt = new Date();
+    }
+    /**
+     * Get the last update timestamp
+     */
+    getLastUpdated() {
+        return this.updatedAt;
+    }
+}

package/dist/multi-agent/checkpointer.d.ts

@@ -0,0 +1,138 @@
+/**
+ * TeamCheckpointer - Persistence for multi-agent teams
+ *
+ * Stores team state alongside project sessions:
+ * ~/.compilr-dev/sessions/{project-id}/
+ * ├── current.json          # Single-agent session (existing)
+ * ├── team.json              # Team metadata
+ * ├── agent-default.json     # Per-agent state
+ * ├── agent-pm.json
+ * ├── agent-arch.json
+ * ├── shared-context.json    # Shared context (Phase 2)
+ * └── artifacts/             # Team artifacts (Phase 2)
+ *     ├── index.json
+ *     └── {id}.json
+ */
+import type { SerializedTeamAgent, TeamMetadata } from './types.js';
+import { AgentTeam, type AgentTeamConfig } from './team.js';
+import { SharedContextManager } from './shared-context.js';
+import { ArtifactStore } from './artifacts.js';
+/**
+ * TeamCheckpointer handles persistence for multi-agent teams
+ */
+export declare class TeamCheckpointer {
+    private readonly sessionsPath;
+    constructor(sessionsPath: string);
+    /**
+     * Get the session directory for a project
+     */
+    private getProjectDir;
+    /**
+     * Get the team metadata file path (terminal-scoped when multi-terminal active)
+     */
+    private getTeamFilePath;
+    /**
+     * Get the agent state file path (terminal-scoped when multi-terminal active)
+     */
+    private getAgentFilePath;
+    /**
+     * Get the shared context file path (terminal-scoped when multi-terminal active)
+     */
+    private getSharedContextPath;
+    /**
+     * Get the artifacts directory path
+     */
+    private getArtifactsPath;
+    /**
+     * Check if a team exists for THIS terminal's project.
+     * Only checks this terminal's scoped file — never cross-terminal.
+     */
+    hasTeam(projectId: number | null): boolean;
+    /**
+     * Save team state
+     */
+    saveTeam(projectId: number | null, team: AgentTeam): void;
+    /**
+     * Load team state for THIS terminal.
+     * Only loads this terminal's scoped files. Never cross-terminal.
+     * For cross-terminal loading, use loadTeamByPrefix().
+     */
+    loadTeam(projectId: number | null, agentFactory: AgentTeamConfig['agentFactory'], onEvent?: AgentTeamConfig['onEvent']): AgentTeam | null;
+    /**
+     * Load team state for a SPECIFIC terminal prefix (cross-terminal resume).
+     * Used when the user explicitly picks another terminal's session to resume.
+     */
+    loadTeamByPrefix(projectId: number | null, terminalPrefix: string, agentFactory: AgentTeamConfig['agentFactory'], onEvent?: AgentTeamConfig['onEvent']): AgentTeam | null;
+    /**
+     * Get the agent count from a team file for a specific terminal prefix.
+     * Lightweight — reads only metadata, doesn't load agents.
+     * Returns 0 if no team file exists (default agent only).
+     */
+    getTeamAgentCountByPrefix(projectId: number | null, terminalPrefix: string): number;
+    /**
+     * Internal: load team from a specific file path with optional terminal prefix for agent files.
+     */
+    private loadTeamFromPath;
+    /**
+     * Save a single agent's state (for incremental updates)
+     */
+    saveAgent(projectId: number | null, agentId: string, agent: SerializedTeamAgent): void;
+    /**
+     * Delete team data for a project
+     */
+    deleteTeam(projectId: number | null): boolean;
+    /**
+     * Claim team files from another terminal by renaming them to this terminal's prefix.
+     * Renames: team-{from}.json, agent-{from}-*.json, shared-context-{from}.json
+     */
+    claimTeamFiles(projectId: number | null, fromPrefix: string, toPrefix: string): boolean;
+    /**
+     * Check if shared context exists for this project
+     */
+    hasSharedContext(projectId: number | null): boolean;
+    /**
+     * Save shared context
+     */
+    saveSharedContext(projectId: number | null, context: SharedContextManager): void;
+    /**
+     * Load shared context
+     */
+    loadSharedContext(projectId: number | null): SharedContextManager | null;
+    /**
+     * Delete shared context
+     */
+    deleteSharedContext(projectId: number | null): boolean;
+    /**
+     * Get artifact store for a project
+     * The ArtifactStore handles its own persistence
+     */
+    getArtifactStore(projectId: number | null): ArtifactStore;
+    /**
+     * Check if artifacts exist for this project
+     */
+    hasArtifacts(projectId: number | null): boolean;
+    /**
+     * Delete all artifacts for a project
+     */
+    deleteArtifacts(projectId: number | null): boolean;
+    /**
+     * Clean up agent files that are no longer in the team
+     */
+    private cleanupOldAgentFiles;
+    /**
+     * List all projects that have team data.
+     */
+    listProjectsWithTeams(): number[];
+    /**
+     * Get team metadata without loading the full team.
+     */
+    getTeamMetadata(projectId: number | null): TeamMetadata | null;
+}
+/**
+ * Get the default sessions path
+ */
+export declare function getSessionsPath(): string;
+/**
+ * Get the shared TeamCheckpointer instance
+ */
+export declare function getTeamCheckpointer(): TeamCheckpointer;